Avatar | Park UI

Installation

npx @park-ui/cli@next add avatar

Add Component

Copy the code snippet below into you components folder.

'use client'
import { Avatar } from '@ark-ui/react/avatar'
import { UserIcon } from 'lucide-react'
import { type ComponentProps, forwardRef } from 'react'
import { createStyleContext } from 'styled-system/jsx'
import { avatar } from 'styled-system/recipes'

const { withProvider, withContext } = createStyleContext(avatar)

export type RootProps = ComponentProps<typeof Root>
export const Root = withProvider(Avatar.Root, 'root')
export const RootProvider = withProvider(Avatar.RootProvider, 'root')
export const Image = withContext(Avatar.Image, 'image', {
  defaultProps: {
    draggable: 'false',
    referrerPolicy: 'no-referrer',
  },
})

export { AvatarContext as Context } from '@ark-ui/react/avatar'

export interface FallbackProps extends ComponentProps<typeof StyledFallback> {
  /**
   * The name to derive the initials from.
   * If not provided, the fallback will display a generic icon.
   */
  name?: string | undefined
}

const StyledFallback = withContext(Avatar.Fallback, 'fallback')

export const Fallback = forwardRef<HTMLDivElement, FallbackProps>(function Fallback(props, ref) {
  const { name, children, asChild, ...rest } = props

  const fallbackContent = children || asChild ? children : name ? getInitials(name) : <UserIcon />

  return (
    <StyledFallback ref={ref} {...rest}>
      {fallbackContent}
    </StyledFallback>
  )
})

const getInitials = (name: string) => {
  const names = name.trim().split(' ')
  const firstName = names[0] || ''
  const lastName = names.length > 1 ? names[names.length - 1] : ''
  return firstName && lastName ? `${firstName[0]}${lastName[0]}` : firstName[0]
}

Integrate Recipe

Integrate this recipe in to your Panda config.

import { avatarAnatomy } from '@ark-ui/react/avatar'
import { defineSlotRecipe } from '@pandacss/dev'

export const avatar = defineSlotRecipe({
  className: 'avatar',
  slots: avatarAnatomy.keys(),
  base: {
    root: {
      display: 'inline-flex',
      alignItems: 'center',
      justifyContent: 'center',
      fontWeight: 'medium',
      position: 'relative',
      verticalAlign: 'top',
      flexShrink: '0',
      userSelect: 'none',
      width: 'var(--avatar-size)',
      height: 'var(--avatar-size)',
      fontSize: 'var(--avatar-font-size)',
      borderRadius: 'var(--avatar-radius)',
      '&[data-group-item]': {
        borderWidth: '0.125em',
        borderColor: 'bg.default',
      },
    },
    fallback: {
      lineHeight: '1',
      textTransform: 'uppercase',
      fontWeight: 'medium',
      fontSize: 'var(--avatar-font-size)',
      borderRadius: 'var(--avatar-radius)',
    },
    image: {
      width: '100%',
      height: '100%',
      objectFit: 'cover',
      borderRadius: 'var(--avatar-radius)',
    },
  },
  defaultVariants: {
    size: 'md',
    shape: 'full',
    variant: 'subtle',
  },
  variants: {
    size: {
      full: {
        root: {
          '--avatar-size': '100%',
          '--avatar-font-size': '100%',
        },
      },
      '2xs': {
        root: {
          '--avatar-font-size': 'fontSizes.2xs',
          '--avatar-size': 'sizes.6',
        },
        fallback: {
          _icon: { width: '3', height: '3' },
        },
      },
      xs: {
        root: {
          '--avatar-font-size': 'fontSizes.xs',
          '--avatar-size': 'sizes.8',
        },
        fallback: {
          _icon: { width: '4', height: '4' },
        },
      },
      sm: {
        root: {
          '--avatar-font-size': 'fontSizes.sm',
          '--avatar-size': 'sizes.9',
        },
        fallback: {
          _icon: { width: '4.5', height: '4.5' },
        },
      },
      md: {
        root: {
          '--avatar-font-size': 'fontSizes.md',
          '--avatar-size': 'sizes.10',
        },
        fallback: {
          _icon: { width: '5', height: '5' },
        },
      },
      lg: {
        root: {
          '--avatar-font-size': 'fontSizes.md',
          '--avatar-size': 'sizes.11',
        },
        fallback: {
          _icon: { width: '5.5', height: '5.5' },
        },
      },
      xl: {
        root: {
          '--avatar-font-size': 'fontSizes.lg',
          '--avatar-size': 'sizes.12',
        },
        fallback: {
          _icon: { width: '6', height: '6' },
        },
      },
      '2xl': {
        root: {
          '--avatar-font-size': 'fontSizes.xl',
          '--avatar-size': 'sizes.16',
        },
        fallback: {
          _icon: { width: '8', height: '8' },
        },
      },
    },
    variant: {
      solid: {
        root: {
          bg: 'colorPalette.solid.bg',
          color: 'colorPalette.solid.fg',
        },
      },
      surface: {
        root: {
          bg: 'colorPalette.surface.bg',
          borderWidth: '1px',
          borderColor: 'colorPalette.surface.border',
          color: 'colorPalette.surface.fg',
        },
      },
      subtle: {
        root: {
          bg: 'colorPalette.subtle.bg',
          color: 'colorPalette.subtle.fg',
        },
      },
      outline: {
        root: {
          borderWidth: '1px',
          borderColor: 'colorPalette.outline.border',
          color: 'colorPalette.outline.fg',
        },
      },
    },
    borderless: {
      true: {
        root: {
          '&[data-group-item]': {
            borderWidth: '0px',
          },
        },
      },
    },
    shape: {
      square: {},
      rounded: {
        root: { '--avatar-radius': 'radii.l3' },
      },
      full: {
        root: { '--avatar-radius': 'radii.full' },
      },
    },
  },
})

Usage

import { Avatar } from '@/components/ui'

<Avatar.Root>
  <Avatar.Image src="https://shorturl.at/gaV8r" />
  <Avatar.Fallback name="Christian Busch" />
</Avatar.Root>

Examples

Sizes

Use the size prop to change the size of the avatar.

Variants

Use the variant prop to change the variant of the avatar.

Shapes

Use the shape prop to change the shape of the avatar.

Fallback

If the image fails to load, the avatar will display the user’s initial. When no name is provided, a generic icon is shown instead.

Colors

Combine the colorPalette prop with some custom logic to dynamically change the color of the avatar.

Ring

Use the outline props to add a ring around the avatar.

Group

The Group component lets you display multiple avatars together. Use the stacking prop to control the order in which avatars overlap.

Badge

Show a badge on the right corner of the avatar by composing the Float and Circle components.

Persona

Here's an example of how to use the Avatar component to display a user persona.

Christian Busch

christian@park-ui.com

Next.js

Here's an example of how to compose the avatar with Next.js Image.

import { getImageProps } from "next/image"
import { Avatar } from "@/components/ui"

export const App = () => {
  const imageProps = getImageProps({
    src: "/image.png",
  })
  return (
    <Avatar.Root>
      <Avatar.Fallback name="Christian Busch" />
      <Avatar.Image {...imageProps} />
    </Avatar.Root>
  )
}

Closed Component

Here's how to setup the avatar for a closed component composition.

import { forwardRef, type ImgHTMLAttributes } from 'react'
import { Avatar as StyledAvatar } from '@/components/ui'

type ImageProps = ImgHTMLAttributes<HTMLImageElement>

export interface AvatarProps extends StyledAvatar.RootProps {
  name?: string
  src?: string
  srcSet?: string
  loading?: ImageProps['loading']
  icon?: React.ReactElement
  fallback?: React.ReactNode
}

export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(props, ref) {
  const { name, src, srcSet, loading, icon, fallback, children, ...rest } = props
  return (
    <StyledAvatar.Root ref={ref} {...rest}>
      <StyledAvatar.Fallback name={name}>{fallback || icon}</StyledAvatar.Fallback>
      <StyledAvatar.Image src={src} srcSet={srcSet} loading={loading} />
      {children}
    </StyledAvatar.Root>
  )
})

Props

Root

Prop	Default	Type
`size`	`'md'`	`'full' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`
`variant`	`'subtle'`	`'solid' \| 'surface' \| 'subtle' \| 'outline'`
`shape`	`'full'`	`'full' \| 'square' \| 'rounded'`
`borderless`		`boolean`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior.
`ids`		`Partial<{ root: string; image: string; fallback: string }>` The ids of the elements in the avatar. Useful for composition.
`onStatusChange`		`(details: StatusChangeDetails) => void` Functional called when the image loading status changes.

Fallback

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior.

Image

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior.