Avatar

Chassis Avatar component displays user identity through images, initials, or icons, with support for sizes, status badges, and stacked groups.

Overview

An <Avatar> displays a user profile as a picture, initials, or an icon, in lists, groups, or as a standalone button.

Basic usage

Render a <Avatar> with text content for initials, or set the src prop to display a profile picture (aliased to alt="Profile Picture" by default).

import { Avatar } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Avatar>CX</Avatar>
      <Avatar src="https://i.pravatar.cc/256" />
    </>
  )
}

Passing a src renders an AvatarImage automatically. Nest one directly for more control over the image itself.

import { Avatar, AvatarImage } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Avatar>
        <AvatarImage src="https://i.pravatar.cc/256" alt="Profile picture" loading="lazy" />
      </Avatar>
    </>
  )
}

Sizes

Set the size prop to one of the Chassis component sizes to adjust the avatar's dimensions.

CXCXCXCXCXCXCX

import { Avatar } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Avatar size="2xs">CX</Avatar>
      <Avatar size="xs">CX</Avatar>
      <Avatar size="sm">CX</Avatar>
      <Avatar>CX</Avatar>
      <Avatar size="lg">CX</Avatar>
      <Avatar size="xl">CX</Avatar>
      <Avatar size="2xl">CX</Avatar>
    </>
  )
}

The --cx-avatar-size CSS variable sets a custom size directly.

CXCX

import { Avatar } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Avatar style={{ '--cx-avatar-size': '1.75rem' } as React.CSSProperties}>CX</Avatar>
      <Avatar style={{ '--cx-avatar-size': '4.25rem' } as React.CSSProperties}>CX</Avatar>
    </>
  )
}

Colors

Set the color prop to one of the Chassis themed colors to apply the appropriate background and text colors.

CXCXCXCXCXCXCXCXCXCXCX

import { Avatar } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Avatar color="default">CX</Avatar>
      <Avatar color="alternate">CX</Avatar>
      <Avatar color="primary">CX</Avatar>
      <Avatar color="secondary">CX</Avatar>
      <Avatar color="neutral">CX</Avatar>
      <Avatar color="danger">CX</Avatar>
      <Avatar color="success">CX</Avatar>
      <Avatar color="warning">CX</Avatar>
      <Avatar color="info">CX</Avatar>
      <Avatar color="black">CX</Avatar>
      <Avatar color="white">CX</Avatar>
    </>
  )
}

Smooth style

Set the smooth prop to create avatars with a subdued background color and matching text color, for a softer, more subtle appearance.

CXCXCXCXCXCXCXCXCXCXCX

import { Avatar } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Avatar color="default" smooth>
        CX
      </Avatar>
      <Avatar color="alternate" smooth>
        CX
      </Avatar>
      <Avatar color="primary" smooth>
        CX
      </Avatar>
      <Avatar color="secondary" smooth>
        CX
      </Avatar>
      <Avatar color="neutral" smooth>
        CX
      </Avatar>
      <Avatar color="danger" smooth>
        CX
      </Avatar>
      <Avatar color="success" smooth>
        CX
      </Avatar>
      <Avatar color="warning" smooth>
        CX
      </Avatar>
      <Avatar color="info" smooth>
        CX
      </Avatar>
      <Avatar color="black" smooth>
        CX
      </Avatar>
      <Avatar color="white" smooth>
        CX
      </Avatar>
    </>
  )
}

Custom components

<Avatar> renders a <button> by default. Set the href prop to render an anchor instead, or set component to render any other tag or custom component. Use the disabled prop to disable a button or anchor avatar.

CXCXCX

import { Avatar } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Avatar>CX</Avatar>
      <Avatar href="#">CX</Avatar>
      <Avatar component="span">CX</Avatar>
    </>
  )
}

Badges

Set the status prop to one of the Chassis themed colors to show a status indicator in the bottom-end corner. It scales with the avatar's size automatically.

import { Avatar } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Avatar src="https://i.pravatar.cc/256" status="success" statusLabel="Online" />
      <Avatar src="https://i.pravatar.cc/256" status="danger" statusLabel="Offline" />
      <Avatar src="https://i.pravatar.cc/256" status="warning" statusLabel="Away" />
      <Avatar src="https://i.pravatar.cc/256" status="neutral" statusLabel="Busy" />
    </>
  )
}

Status colors alone can be confusing for screen reader users. Set statusLabel to describe what the badge conveys — it's rendered as visually hidden text on the badge. Without it, the status value itself (e.g. "success") is used as a fallback.

Stacks

Use <AvatarStack> to group related avatars together with a consistent overlap. Pass a data array to render a Avatar per item, or nest <Avatar> children directly — handy for a trailing "+N" overflow avatar. Set the --cx-avatar-stack-spacing CSS variable to adjust how much they overlap, and use the size prop to size every avatar in the stack at once.

import { Avatar, AvatarStack } from '@chassis-ui/react'

export const Example = () => {
  const randomAvatar = () => `https://i.pravatar.cc/256?u=${Math.floor(Math.random() * 64)}`
  return (
    <>
      <AvatarStack
        items={[
          {
            src: randomAvatar(),
            alt: 'Team member'
          },
          {
            src: randomAvatar(),
            alt: 'Team member'
          },
          {
            src: randomAvatar(),
            alt: 'Team member'
          }
        ]}
      >
        <Avatar component="span">+5</Avatar>
      </AvatarStack>
    </>
  )
}

import { AvatarStack } from '@chassis-ui/react'

export const Example = () => {
  const randomAvatar = () => `https://i.pravatar.cc/256?u=${Math.floor(Math.random() * 64)}`
  return (
    <>
      <AvatarStack
        size="sm"
        items={[
          {
            content: '+5',
            component: 'span'
          },
          {
            src: randomAvatar(),
            alt: 'Team member'
          },
          {
            src: randomAvatar(),
            alt: 'Team member'
          },
          {
            src: randomAvatar(),
            alt: 'Team member'
          }
        ]}
      ></AvatarStack>
    </>
  )
}

API

Avatar

Prop	Type	Default
`alt?`	`string`	—
Alt text for the image rendered when `src` is set.
`asChild?`	`boolean`	—
Render the single child element in place of this component's own element, with this component's classes, props and ref merged onto it: `<Button asChild><Link href="/login">Log in</Link></Button>`. The alternative to `component` for React Server Components — an element can be passed from the server to this package's client components, a component reference (`component={Link}`) can't.
`className?`	`string`	—
A string of all className you want applied to the component.
`color?`	`ContextColor`	—
Sets the color of the component to one of Chassis context colors.
`component?`	`ElementType`	—
Component used for the root node. Either a string to use a HTML element or a component. Defaults to `span`, or `a` when `href` is set. Set explicitly to `button` (or another interactive element/component) to make a non-link avatar focusable and clickable.
`disabled?`	`boolean`	—
Toggle the disabled state for the component. Only applies when `component` is `a` or `button`.
`href?`	`string`	—
Renders the avatar as a link to this URL. Defaults `component` to `a`. Passed through to a custom `component` too, regardless of whether it resolves to a native `a`/`button`.
`ref?`	`any`	—

`size?`	`ExtendedSizing`	—
Sets the size of the component to one of Chassis component sizes.
`smooth?`	`boolean`	—
Renders the smooth (tinted background) context variant instead of the solid default.
`src?`	`string`	—
Image source. When set, renders an `AvatarImage` in place of `children`.
`status?`	`ContextColor`	—
Renders a status badge in the bottom-end corner, in one of the Chassis themed colors.
`statusLabel?`	`string`	—
Accessible label for the status badge, exposed to assistive tech as visually hidden text. Falls back to the `status` value itself.

AvatarImage

Prop	Type	Default
`className?`	`string`	—
A string of all className you want applied to the component.

AvatarStack

Prop	Type	Default
`asChild?`	`boolean`	—
Render the single child element in place of this component's own element, with this component's classes, props and ref merged onto it: `<Button asChild><Link href="/login">Log in</Link></Button>`. The alternative to `component` for React Server Components — an element can be passed from the server to this package's client components, a component reference (`component={Link}`) can't.
`className?`	`string`	—
A string of all className you want applied to the component.
`component?`	`ElementType`	—
Component used for the root node. Either a string to use a HTML element or a component.
`items?`	`AvatarStackItemDef[]`	—
Renders a `Avatar` for each item, ahead of any JSX `children` (handy for a trailing "+N" overflow avatar).
`ref?`	`any`	—

`size?`	`ExtendedSizing`	—
Sets the size of every `Avatar` in the stack to one of Chassis component sizes.

AvatarStackItemDef

Shape of each entry in AvatarStack's items array.

Prop	Type	Default
`alt?`	`string`	—
Alt text for the image rendered when `src` is set.
`component?`	`ElementType`	—
Component used for the root node. Either a string to use a HTML element or a component.
`content?`	`ReactNode`	—
Content to render when `src` isn't set, e.g. initials or a "+5" overflow count.
`href?`	`string`	—
Renders the avatar as a link to this URL.
`key?`	`string \| number`	—
React key for the rendered `Avatar`. Falls back to the item's index in `data`.
`src?`	`string`	—
Image source, rendered via `AvatarImage`.
`status?`	`ContextColor`	—
Renders a status badge in one of the Chassis themed colors.
`statusLabel?`	`string`	—
Accessible label for the status badge.