Use blurhash for image loading status

Author: LauraBeatris

packages/clerk-js/src/core/resources/OrganizationCreationDefaults.ts

@@ -18,10 +18,12 @@ export class OrganizationCreationDefaults extends BaseResource implements Organi
     name: string;
     slug: string;
     logo: string | null;
+    blurHash: string | null;
   } = {
     name: '',
     slug: '',
     logo: null,
+    blurHash: null,
   };
 
   public constructor(data: OrganizationCreationDefaultsJSON | OrganizationCreationDefaultsJSONSnapshot | null = null) {
@@ -42,6 +44,7 @@ export class OrganizationCreationDefaults extends BaseResource implements Organi
       this.form.name = this.withDefault(data.form.name, this.form.name);
       this.form.slug = this.withDefault(data.form.slug, this.form.slug);
       this.form.logo = this.withDefault(data.form.logo, this.form.logo);
+      this.form.blurHash = this.withDefault(data.form.blur_hash, this.form.blurHash);
     }
 
     return this;

packages/shared/src/types/organizationCreationDefaults.ts

@@ -15,6 +15,7 @@ export interface OrganizationCreationDefaultsJSON extends ClerkResourceJSON {
     name: string;
     slug: string;
     logo: string | null;
+    blur_hash: string | null;
   };
 }
 
@@ -28,5 +29,6 @@ export interface OrganizationCreationDefaultsResource extends ClerkResource {
     name: string;
     slug: string;
     logo: string | null;
+    blurHash: string | null;
   };
 }

packages/ui/package.json

@@ -79,6 +79,7 @@
     "@solana/wallet-adapter-react": "catalog:module-manager",
     "@solana/wallet-standard": "catalog:module-manager",
     "@swc/helpers": "catalog:repo",
+    "blurhash": "^2.0.5",
     "copy-to-clipboard": "3.3.3",
     "core-js": "catalog:repo",
     "csstype": "3.1.3",

packages/ui/src/components/OrganizationProfile/OrganizationProfileAvatarUploader.tsx

@@ -8,9 +8,13 @@ import { Col, descriptors, Text } from '../../customizables';
 import { localizationKeys } from '../../localization';
 
 export const OrganizationProfileAvatarUploader = (
-  props: Omit<AvatarUploaderProps, 'avatarPreview' | 'title'> & { organization: Partial<OrganizationResource> },
+  props: Omit<AvatarUploaderProps, 'avatarPreview' | 'title'> & {
+    organization: Partial<OrganizationResource>;
+    /** A data URL to show as a placeholder while the image is loading (e.g., decoded blurhash) */
+    blurHashPlaceholder?: string;
+  },
 ) => {
-  const { organization, ...rest } = props;
+  const { organization, blurHashPlaceholder, ...rest } = props;
 
   return (
     <Col elementDescriptor={descriptors.organizationAvatarUploaderContainer}>
@@ -28,6 +32,7 @@ export const OrganizationProfileAvatarUploader = (
         avatarPreview={
           <OrganizationAvatar
             size={theme => theme.sizes.$16}
+            blurHashPlaceholder={blurHashPlaceholder}
             {...organization}
           />
         }

packages/ui/src/components/SessionTasks/tasks/TaskChooseOrganization/CreateOrganizationScreen.tsx

@@ -1,6 +1,6 @@
 import { useOrganizationList } from '@clerk/shared/react';
 import type { CreateOrganizationParams, OrganizationCreationDefaultsResource } from '@clerk/shared/types';
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 
 import { useEnvironment } from '@/ui/contexts';
 import { useSessionTasksContext, useTaskChooseOrganizationContext } from '@/ui/contexts/components/SessionTasks';
@@ -12,6 +12,7 @@ import { FormContainer } from '@/ui/elements/FormContainer';
 import { Header } from '@/ui/elements/Header';
 import { IconButton } from '@/ui/elements/IconButton';
 import { Upload } from '@/ui/icons';
+import { decodeBlurHash } from '@/ui/utils/blurhash';
 import { createSlug } from '@/ui/utils/createSlug';
 import { handleError } from '@/ui/utils/errorHandler';
 import { useFormControl } from '@/ui/utils/useFormControl';
@@ -100,6 +101,10 @@ export const CreateOrganizationScreen = (props: CreateOrganizationScreenProps) =
 
   const isSubmitButtonDisabled = !nameField.value || !isLoaded;
   const defaultLogoUrl = file === undefined ? props.organizationCreationDefaults?.form.logo : undefined;
+  const blurHashPlaceholder = useMemo(
+    () => decodeBlurHash(props.organizationCreationDefaults?.form.blurHash),
+    [props.organizationCreationDefaults?.form.blurHash],
+  );
 
   return (
     <>
@@ -118,6 +123,7 @@ export const CreateOrganizationScreen = (props: CreateOrganizationScreenProps) =
             organization={{ name: nameField.value, imageUrl: defaultLogoUrl ?? undefined }}
             onAvatarChange={async file => await setFile(file)}
             onAvatarRemove={file || defaultLogoUrl ? onAvatarRemove : null}
+            blurHashPlaceholder={defaultLogoUrl ? blurHashPlaceholder : undefined}
             avatarPreviewPlaceholder={
               <IconButton
                 variant='ghost'

packages/ui/src/elements/Avatar.tsx

@@ -15,6 +15,8 @@ type AvatarProps = PropsOfComponent<typeof Flex> & {
   rounded?: boolean;
   boxElementDescriptor?: ElementDescriptor;
   imageElementDescriptor?: ElementDescriptor;
+  /** A data URL to show as a placeholder while the image is loading (e.g., decoded blurhash) */
+  blurHashPlaceholder?: string;
 };
 
 export const Avatar = (props: AvatarProps) => {
@@ -28,8 +30,16 @@ export const Avatar = (props: AvatarProps) => {
     sx,
     boxElementDescriptor,
     imageElementDescriptor,
+    blurHashPlaceholder,
   } = props;
   const [error, setError] = React.useState(false);
+  const [loaded, setLoaded] = React.useState(false);
+
+  // Reset loaded state when imageUrl changes
+  React.useEffect(() => {
+    setLoaded(false);
+    setError(false);
+  }, [imageUrl]);
 
   const ImgOrFallback =
     initials && (!imageUrl || error) ? (
@@ -40,8 +50,15 @@ export const Avatar = (props: AvatarProps) => {
         title={title}
         alt={`${title}'s logo`}
         src={imageUrl || ''}
-        sx={{ objectFit: 'cover', width: '100%', height: '100%' }}
+        sx={{
+          objectFit: 'cover',
+          width: '100%',
+          height: '100%',
+          opacity: loaded ? 1 : 0,
+          transition: 'opacity 0.2s ease-in-out',
+        }}
         onError={() => setError(true)}
+        onLoad={() => setLoaded(true)}
         size={imageFetchSize}
       />
     );
@@ -61,6 +78,13 @@ export const Avatar = (props: AvatarProps) => {
           backgroundColor: t.colors.$avatarBackground,
           backgroundClip: 'padding-box',
           position: 'relative',
+          ...(blurHashPlaceholder && !loaded && imageUrl
+            ? {
+                backgroundImage: `url(${blurHashPlaceholder})`,
+                backgroundSize: 'cover',
+                backgroundPosition: 'center',
+              }
+            : {}),
         }),
         sx,
       ]}

packages/ui/src/elements/OrganizationAvatar.tsx

@@ -4,15 +4,19 @@ import type { PropsOfComponent } from '../styledSystem';
 import { Avatar } from './Avatar';
 
 type OrganizationAvatarProps = PropsOfComponent<typeof Avatar> &
-  Partial<Pick<OrganizationResource, 'name' | 'imageUrl'>>;
+  Partial<Pick<OrganizationResource, 'name' | 'imageUrl'>> & {
+    /** A data URL to show as a placeholder while the image is loading (e.g., decoded blurhash) */
+    blurHashPlaceholder?: string;
+  };
 
 export const OrganizationAvatar = (props: OrganizationAvatarProps) => {
-  const { name = '', imageUrl, ...rest } = props;
+  const { name = '', imageUrl, blurHashPlaceholder, ...rest } = props;
   return (
     <Avatar
       title={name}
       initials={(name || ' ')[0]}
       imageUrl={imageUrl}
+      blurHashPlaceholder={blurHashPlaceholder}
       rounded={false}
       {...rest}
     />

packages/ui/src/utils/blurhash.ts

@@ -0,0 +1,31 @@
+import { decode } from 'blurhash';
+
+/**
+ * Decodes a blurhash string to a data URL that can be used as an image src or background
+ * @internal
+ */
+export function decodeBlurHash(blurHash: string | null | undefined, width = 32, height = 32): string | undefined {
+  if (!blurHash) {
+    return undefined;
+  }
+
+  try {
+    const pixels = decode(blurHash, width, height);
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+
+    if (!ctx) {
+      return undefined;
+    }
+
+    const imageData = ctx.createImageData(width, height);
+    imageData.data.set(pixels);
+    ctx.putImageData(imageData, 0, 0);
+
+    return canvas.toDataURL();
+  } catch {
+    return undefined;
+  }
+}