Avatar

Distinct identities with softly colored initials, images, presence indicators, and optional rings. Compose overlapping teams with Avatar.Group and an accessible overflow count.

View source Installation

Preview

THE PEOPLE BEHIND IT

A little more human.

Give every collaborator a recognizable place in your product.

Maya ChenProduct designer

Alex MorganFrontend engineer

Sam RiveraDesign engineer

Jamie ParkerAvailable for a good idea

Display name

Presence

One identity. Every scale.

From a quiet mention to the face of a profile.

square

Import

import { Avatar } from '@velocityuikit/velocityui'

Props

Prop	Type	Default	Description
src	`string`	—	URL of the avatar image.
alt	`string`	—	Alt text for the image.
name	`string`	—	Full name used to generate initials when no image is available.
size	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Controls the overall dimensions of the avatar.
shape	`'circle' \| 'square'`	`'circle'`	Border radius shape.
status	`'online' \| 'away' \| 'busy' \| 'offline'`	—	Shows a presence indicator and includes the status in the accessible name.
tone	`'auto' \| 'neutral' \| 'blue' \| 'violet' \| 'rose' \| 'amber' \| 'emerald'`	`'auto'`	Initials color treatment. Auto chooses a stable color from the name.
ring	`boolean`	`false`	Adds a separated accent ring around the avatar.
statusAnimation	`'none' \| 'pulse'`	`'none'`	Adds a pulsing live-status ring when a status indicator is shown.

Examples

Teams and overflow

Avatar.Group accepts Avatar children, a shared size (md by default), and max visible members (5 by default). Hidden names remain available in the overflow label. Use --vui-avatar-ring to match the surrounding surface.

import { Avatar } from '@velocityuikit/velocityui'

export default function Team() {
  return (
    <Avatar.Group max={3} size="md" aria-label="Project contributors">
      <Avatar name="Maya Chen" tone="violet" />
      <Avatar name="Alex Morgan" tone="blue" />
      <Avatar name="Sam Rivera" tone="emerald" />
      <Avatar name="Jamie Parker" />
      <Avatar name="Taylor Kim" />
    </Avatar.Group>
  )
}

Sizes

import { Avatar } from '@velocityuikit/velocityui'

export default function Example() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '0.75rem' }}>
      <Avatar name="Alice Brown" size="xs" />
      <Avatar name="Alice Brown" size="sm" />
      <Avatar name="Alice Brown" size="md" />
      <Avatar name="Alice Brown" size="lg" />
      <Avatar name="Alice Brown" size="xl" />
    </div>
  )
}

With status

import { Avatar } from '@velocityuikit/velocityui'

export default function Example() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '0.75rem' }}>
      <Avatar name="Sam Lee" status="online" />
      <Avatar name="Jordan Kim" status="away" />
      <Avatar name="Alex Ng" status="offline" />
    </div>
  )
}

Animated live status

import { Avatar } from '@velocityuikit/velocityui'

export default function Example() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '0.75rem' }}>
      <Avatar name="Sam Lee" status="online" statusAnimation="pulse" />
      <Avatar name="Jordan Kim" status="away" statusAnimation="pulse" />
    </div>
  )
}

Theming

Apply a named theme class to <body> or any parent element. All VelocityUI components inside that element will automatically adopt its colors, shadows, and effects. Combine with a density modifier for complete control:

/* Pick any named theme */
<body class="vui-theme-ocean">

/* Add a density modifier (optional) */
<body class="vui-theme-midnight vui-density-compact">
<body class="vui-theme-construction vui-density-spacious">

/* Available themes */
/* default  midnight  ocean  dark-cyan  tangerine */
/* construction  glass  soft  high-contrast  monochrome-red */

/* Available densities */
/* vui-density-compact  vui-density-comfortable  vui-density-spacious */