Components

Avatar

Image with initials fallback in four sizes, two shapes, and five tones

import { Avatar, AvatarFallback, AvatarImage } from "@nyte-ai/ui";

An image that falls back to initials while it loads or when it fails.

Usage

Always include AvatarFallback. It renders until the image loads and again if the image fails.
Fallback text is two characters. Nothing longer fits at xs.
tone is for identity, not status. Do not use green to mean online.
AvatarImage needs alt. If the avatar sits beside the name it repeats, use alt="".

Anatomy

<Avatar>
  <AvatarImage />
  <AvatarFallback />
</Avatar>

Examples

Sizes and shapes

ILNYSMXS

<Avatar size="lg">
  <AvatarImage src="…" alt="interfaces-lab" />
  <AvatarFallback>IL</AvatarFallback>
</Avatar>
<Avatar size="md"><AvatarFallback>NY</AvatarFallback></Avatar>
<Avatar size="sm" shape="rounded"><AvatarFallback>SM</AvatarFallback></Avatar>
<Avatar size="xs" shape="rounded"><AvatarFallback>XS</AvatarFallback></Avatar>

Tones

NEORBLVIGR

<Avatar tone="neutral"><AvatarFallback>NE</AvatarFallback></Avatar>
<Avatar tone="orange"><AvatarFallback>OR</AvatarFallback></Avatar>
<Avatar tone="blue"><AvatarFallback>BL</AvatarFallback></Avatar>
<Avatar tone="violet"><AvatarFallback>VI</AvatarFallback></Avatar>
<Avatar tone="green"><AvatarFallback>GR</AvatarFallback></Avatar>

Props

The reference tables below come from Base UI, MIT, © Material-UI SAS.

Avatar

Prop	Type	Default	Description
`size`	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`	20, 24, 28, or 36px.
`shape`	`"circle" \| "rounded"`	`"circle"`	Full circle or rounded square.
`tone`	`"neutral" \| "orange" \| "blue" \| "violet" \| "green"`	`"neutral"`	Background and foreground pair.
`className`, `style`, `xstyle`	see Theming

size and tone are also reflected as data-size and data-tone on the root.

Displays a user's profile picture, initials, or fallback icon. Renders a <span> element.

Root Props:

Prop	Type	Default	Description
className	`string \| ((state: Avatar.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Avatar.Root.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Avatar.Root.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

AvatarImage

The image to be displayed in the avatar. Renders an <img> element.

Image Props:

Prop	Type	Default	Description
onLoadingStatusChange	`((status: ImageLoadingStatus) => void)`	-	Callback fired when the loading status changes.
className	`string \| ((state: Avatar.Image.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Avatar.Image.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted	`boolean`	`false`	Whether the image element stays mounted and loads in place instead of being preloaded. Supports `loading="lazy"` and optimized image components such as `next/image`.
render	`ReactElement \| ((props: React.DetailedHTMLProps<React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, state: Avatar.Image.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Image Data Attributes:

Attribute	Type	Description
data-error	-	Present when the image failed to load.
data-loading	-	Present while the image is loading.
data-starting-style	-	Present when the image begins animating in.
data-ending-style	-	Present when the image is animating out.

AvatarFallback

Rendered when the image fails to load or when no image is provided. Renders a <span> element.

Fallback Props:

Prop	Type	Default	Description
delay	`number`	`0`	How long to wait before showing the fallback. Specified in milliseconds.
className	`string \| ((state: Avatar.Fallback.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Avatar.Fallback.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Avatar.Fallback.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Accessibility

The root is a <span> with no role. Meaning comes from the image's alt or the text around it.
The fallback shows while the image loads and after it errors. delay on the fallback avoids a flash for fast loads.