components / avatar

Avatar

Image or initial fallback surface with size, shape, and ring visibility recipes.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Avatar gives DK a consistent personal or entity marker without forcing teams to invent fallback styles and sizing each time.
  • It supports either imagery or initials while staying aligned with system surface and ring rules.

Aliases

user avatar

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Avatar when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Avatar contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Avatar label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Avatar behind decorative copy or overloaded surface treatments.
  • Do not stretch Avatar into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

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

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

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

Anti-patterns

  • Using Avatar as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy avatar usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

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.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

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'Chooses the compiled size recipe for the component.
shape'circle' | 'rounded''circle'Chooses the avatar silhouette.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Slots

NameDescription
defaultAvatar is prop-driven in v1 and does not expose content slots.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

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

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

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

Keyboard

  • No custom keyboard behavior in v1.

Screen readers

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

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

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

  • Avatar stays intentionally small in scope; group and presence patterns should be composed around it instead of added into it.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: initials fallback

A default fallback avatar using initials derived from the name.

Copy snippet

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

Common patterns

1 example

common

Common: image-backed identity

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

Copy snippet

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

Edge cases

1 example

edge

Edge: rounded entity marker

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

Copy snippet

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

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

small-circle

pass

shape=circle|size=sm

  • Contrast: 89.9 Lc
  • Target: 32px

medium-circle

pass

shape=circle|size=md

  • Contrast: 89.9 Lc
  • Target: 44px

large-rounded

pass

shape=rounded|size=lg

  • Contrast: 89.9 Lc
  • Target: 56px