Avatar

Image or initials with configurable size, shape, and ring.

Overview

  • Provide alternative text for an identifying image and initials when an image is unavailable.

Aliases

user avatar

When to use

  • Use Avatar for people, teams, or system identities that benefit from a compact visual marker.
  • Use initials fallback when images are unavailable or optional.

When not to use

  • Do not treat Avatar as a badge or status indicator by itself.
  • Do not overload the component with group or stack behavior.

Structural parts

avatar shell

root

Carries shape, size, and ring treatment.

optional visual asset

image

Shows the supplied image when available.

initials fallback

fallback

Shows derived initials when no image exists.

Public interface

Props
NameTypeDefaultDescription
namestring—Source for initials fallback and labeling.
srcstring—Optional image source.
altstring—Optional alt text for meaningful imagery.
size'sm' | 'md' | 'lg''md'Sets the component size.
shape'circle' | 'rounded''circle'Chooses the avatar silhouette.
themeThemeContract—Sets the theme used to resolve component styles.
Slots
NameDescription
defaultAvatar is prop-driven and does not expose content slots.

Variants, sizes, and states

Variants

  • circle: Default circular identity marker.
  • rounded: Rounded-rectangle identity marker with softer geometry.

Sizes

  • sm: Compact identity marker for lists and metadata.
  • md: Default avatar size.
  • lg: Larger identity surface for headers and detail views.

States

  • image: Image-backed avatar
  • fallback: Initials-backed avatar

Accessibility

Semantics

  • Avatar acts as supporting identity media rather than an interactive control.

Keyboard

  • No custom keyboard behavior.

Screen readers

  • When the avatar is meaningful content, supply a useful alt; otherwise keep decorative usage silent.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-avatar-bg
#d7e9ff
--dk-avatar-fg
#000f4d
--dk-avatar-ring
#95989d
--dk-avatar-size
44px
--dk-avatar-radius
999px
--dk-avatar-ring-width
1px

image

--dk-avatar-image-radius
inherit

fallback

--dk-avatar-fallback-color
inherit
--dk-avatar-fallback-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-avatar-fallback-weight
700

Implementation notes

  • Compose avatar groups and presence indicators outside the component.

Examples

Starter

Initials fallback

A default fallback avatar using initials derived from the name.

<Avatar name="Design Kit" size="md" />

Common patterns

Image-backed identity

Provide src and useful alt text when the image itself matters.

<Avatar name="Anika Rose" src="/images/anika.jpg" alt="Anika Rose" size="sm" />

Edge cases

Rounded entity marker

Rounded shape works well for teams or non-person entities.

<Avatar name="Relaunch Team" shape="rounded" size="lg" />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

small-circle

pass

shape=circle|size=sm

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 89.9 Lc
  • Target: 32 px

medium-circle

pass

shape=circle|size=md

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 89.9 Lc
  • Target: 44 px

large-rounded

pass

shape=rounded|size=lg

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 89.9 Lc
  • Target: 56 px