Primitives

Avatar

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

Import

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

Implemented in packages/ui/src/components/ui/avatar.tsx, wrapping @base-ui/react/avatar (no dedicated headless subpath; the styled wrapper is the only export).

Usage

Always include AvatarFallback. The image can fail, and the fallback is what a screen reader user and a slow network both get.
Fallback text is two characters. The font sizes are tuned for that and nothing longer fits at xs.
tone is for identity (a participant, an agent), not for status. Do not use green to mean online.
AvatarImage needs alt. If the avatar is decorative beside the participant's name, alt="".

Anatomy

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

Avatar renders a <span> with data-slot="avatar", data-size, and data-tone. Image and fallback set data-slot="avatar-image" and data-slot="avatar-fallback".

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

Props

Avatar

Prop	Type	Default	Description
`size`	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`	20, 24, 28, or 36px.
`shape`	`"circle" \| "rounded"`	`"circle"`	Pill radius or `--nyte-radius-avatar` (42%).
`tone`	`"neutral" \| "orange" \| "blue" \| "violet" \| "green"`	`"neutral"`	Background and foreground pair.
`className`, `style`, `xstyle`	see Theming

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>; it has no role. Meaning comes from the image's alt or from the text around it.
Base UI tracks image loading status and swaps to the fallback on error or while loading; delay on the fallback avoids a flash for fast loads.

Styling

Token	Role
`--nyte-avatar-size-`, `--nyte-avatar-font-`	Per-size box and fallback font
`--nyte-avatar-ring-width`	0.5px border in `--nyte-color-border`
`--nyte-color-avatar-*-background` / `-foreground`	Per-tone pair
`--nyte-radius-avatar`, `--nyte-radius-pill`	Shapes
`--nyte-font-weight-semibold`	Fallback weight