Avatar

Avatar is a component that displays a profile picture or an icon with initials representing a user.

<Avatar
  name="Hirotomo Yamada"
  src="https://avatars.githubusercontent.com/u/84060430?v=4"
/>

Usage

import { Avatar, AvatarGroup } from "@yamada-ui/react"

import { Avatar, AvatarGroup } from "@/components/ui"

import { Avatar, AvatarGroup } from "@workspaces/ui"

<Avatar />

<AvatarGroup.Root>
  <AvatarGroup.Item />
</AvatarGroup.Root>

Change Variant

<Wrap gap="md">
  <For each={["solid", "subtle", "surface", "outline"]}>
    {(variant, key) => (
      <Avatar variant={variant} name="Hirotomo Yamada" key={key} />
    )}
  </For>
</Wrap>

Change Size

<Wrap gap="md">
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size, key) => <Avatar size={size} name="Hirotomo Yamada" key={key} />}
  </For>
</Wrap>

Change Shape

<Wrap gap="md">
  <For each={["circle", "square", "rounded"]}>
    {(size, key) => <Avatar shape={size} name="Hirotomo Yamada" key={key} />}
  </For>
</Wrap>

Display Initials

When you set a string to name, an icon with the user's initials will be displayed.

<Avatar name="Hirotomo Yamada" />

Display an Image

If you want to display an image in the avatar, set the path to src.

<Avatar src="https://avatars.githubusercontent.com/u/84060430?v=4" />

Fallback

There are two fallbacks if the loading of src fails:

If name is provided: It uses an icon with the user's initials
If name is not provided: It uses the default avatar icon.

<Wrap gap="md">
  <Avatar
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <Avatar name="Hirotomo Yamada" src="https://not-found.com" />
  <Avatar src="https://not-found.com" />
</Wrap>

Customize the Fallback

Here is an example of customizing the fallback icon and background color.

<Wrap gap="md">
  <Avatar bg="warning" src="https://not-found.com" />
  <Avatar icon={<GhostIcon />} src="https://not-found.com" />
</Wrap>

Use random color

const randomColorScheme = (name: string) => {
  const index = name.charCodeAt(0) % COLOR_SCHEMES.length
  return COLOR_SCHEMES[index]
}

return (
  <Wrap gap="md">
    <For each={["Hirotomo Yamada", "Koiso Kenji", "Shinohara Natsuki"]}>
      {(name, index) => (
        <Avatar key={index} name={name} colorScheme={randomColorScheme(name)} />
      )}
    </For>
  </Wrap>
)

Grouping

If you want to control the number of avatars displayed, specify a number with max. If there are more avatars than the specified number, it truncates and displays the remaining avatars as +X.

<AvatarGroup.Root max={3}>
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
</AvatarGroup.Root>

Props

Avatar

Prop	Default	Type / Description
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	`"md"`	`"lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	`"solid"`	`"outline" \| "solid" \| "subtle" \| "surface"` The variant of the component.
`alt`	-	`HTMLProps<"img">["alt"]` The `HTMLImageElement` property `alt`.
`crossOrigin`	-	`HTMLProps<"img">["crossOrigin"]` The `HTMLImageElement` property `crossOrigin`.
`fallback`	-	`ReactNode` The fallback text to display if the image is not provided.
`fallbackProps`	-	`AvatarFallbackProps` The props to pass to the fallback component.
`format`	-	`(name: string) => string` Function to get the initials to display.
`icon`	-	`ReactElement` The avatar icon to use.
`imageProps`	-	`AvatarImageProps` The props to pass to the image component.
`loading`	-	`HTMLProps<"img">["loading"]` Defines loading strategy.
`name`	-	`string` The name of the person in the avatar. - If `src` has loaded, the name will be used as the `alt` attribute of the `img` - If `src` is not loaded, the name will be used to create the initials
`referrerPolicy`	`"no-referrer"`	`HTMLProps<"img">["referrerPolicy"]` Defining which referrer is sent when fetching the resource.
`shape`	`"circle"`	`"circle" \| "rounded" \| "square"` The shape of the component
`src`	-	`HTMLProps<"img">["src"]` The image url of the avatar.
`srcSet`	-	`HTMLProps<"img">["srcSet"]` List of sources to use for different screen resolutions.

AvatarGroup.Root

Prop	Default	Type / Description
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	`"md"`	`"lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	`"solid"`	`"outline" \| "solid" \| "subtle" \| "surface"` The variant of the component.
`max`	-	`number` The maximum number of visible avatars.
`reverse`	-	`boolean` Whether to reverse the order of the avatars.
`shape`	`"circle"`	`"circle" \| "rounded" \| "square"` The shape of the component

AvatarGroup.Item

Prop	Default	Type / Description
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	`"md"`	`"lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	`"solid"`	`"outline" \| "solid" \| "subtle" \| "surface"` The variant of the component.
`alt`	-	`HTMLProps<"img">["alt"]` The `HTMLImageElement` property `alt`.
`crossOrigin`	-	`HTMLProps<"img">["crossOrigin"]` The `HTMLImageElement` property `crossOrigin`.
`fallback`	-	`ReactNode` The fallback text to display if the image is not provided.
`fallbackProps`	-	`AvatarFallbackProps` The props to pass to the fallback component.
`format`	-	`(name: string) => string` Function to get the initials to display.
`icon`	-	`ReactElement` The avatar icon to use.
`imageProps`	-	`AvatarImageProps` The props to pass to the image component.
`loading`	-	`HTMLProps<"img">["loading"]` Defines loading strategy.
`name`	-	`string` The name of the person in the avatar. - If `src` has loaded, the name will be used as the `alt` attribute of the `img` - If `src` is not loaded, the name will be used to create the initials
`referrerPolicy`	`"no-referrer"`	`HTMLProps<"img">["referrerPolicy"]` Defining which referrer is sent when fetching the resource.
`shape`	`"circle"`	`"circle" \| "rounded" \| "square"` The shape of the component
`src`	-	`HTMLProps<"img">["src"]` The image url of the avatar.
`srcSet`	-	`HTMLProps<"img">["srcSet"]` List of sources to use for different screen resolutions.

Accessibility

ARIA Roles and Attributes

Component	Roles and Attributes	Usage
`AvatarImage`	`alt`	Alternative text for the avatar image. The component uses the `name` prop as the value for the `alt` attribute; if `name` is not provided, it uses the `alt` prop value instead.
`AvatarFallback`	`role="img"`	Indicates that this is an image.
	`aria-label`	This is set when `fallback` is not provided. Sets the value of `name` or `alt` if provided. Otherwise, sets `"Avatar Icon"`.
`AvatarGroup.Root`	`role="group"`	Indicates that it is a group.