Stepwise UI

Avatar

Circular user representation in two variants - a neutral-fill initial, or a photo. Stack them in an overlapping group with a + button wired to your invite flow.

Installation

npx stepwise-ui add avatar

Default

A neutral fill with a zinc initial.
A
N
Y
M
<Avatar name="Asta" />

Accent

Pass textClassName for a different accent color.
A
N
Y
M
<Avatar name="Asta" textClassName="text-sky-600 dark:text-sky-400" />

Letters

Pass letters={2} for two initials instead of one.
A
N
Y
M
1 letter (default)
AS
NS
YS
MS
2 letters
<Avatar name="Asta" />                 // 1 letter (default)
<Avatar name="Asta" letters={2} />     // 2 letters

Image

Pass any URL as src to use your own picture - it fills the circle by default, no extra setup. The 5 characters shown here are this docs site's own illustrations, not part of the installed component; copy the SVGs from public/avatars if you want them, or point src at anything else - a real photo needs nothing more than that. They're cropped with imagePosition="top" so the crop favors the face over the chest below it.
Mira
Kai
Yuna
Theo
Snoofy
// Your own photo - fills the circle edge to edge, cropped. This is
// the default: any URL works, nothing extra to configure.
<Avatar name="Asta" src="/your-photo.jpg" />

// This site's own 5 illustrated characters (shown above), copied into
// /public/avatars - object-position "top" keeps the crop on the face
// instead of centering on the chest below it.
<Avatar name="Snoofy" src="/avatars/avatar5.svg" imagePosition="top" />

// Falls back to the letter variant automatically if the photo 404s

Badge

A small status dot on the bottom-right edge. Pass badge with one of the four presence states below.
Mira
online
Mira
away
Mira
busy
Mira
offline
<Avatar name="Mira" src="/avatars/avatar1.svg" badge="online" />
<Avatar name="Mira" src="/avatars/avatar1.svg" badge="away" />
<Avatar name="Mira" src="/avatars/avatar1.svg" badge="busy" />
<Avatar name="Mira" src="/avatars/avatar1.svg" badge="offline" />

Avatar Group

Hover any avatar to see their name. Hover the +N overflow pill to see everyone it's hiding. Pass onAdd to get the dashed + button - wire it up to whatever your invite flow needs.
A
N
Y
M
L
1 letter, default color
AS
NS
YS
MS
LV
2 letters, alternating accent
import { AvatarGroup } from '@/components/stepwise/avatar'

<AvatarGroup
  avatars={team}
  max={5}
  onAdd={() => {/* your invite flow */}}  // renders the + button
/>

Sizes

A
xs
A
sm
A
default
A
lg
import { Avatar } from '@/components/stepwise/avatar'

<Avatar name="Asta" />                    // default
<Avatar name="Asta" src="/photo.jpg" />   // image

Props - Avatar

PropTypeDescription
src
string
Image URL. Falls back to the default variant if absent or broken.
name
string
Drives the initial(s).
variant
"letter" | "image"
Defaults to "image" when src is set, else "letter".
size
"xs" | "sm" | "default" | "lg"
Default "default" (2.5rem / 40px).
letters
1 | 2
How many initials to show. Default 1.
imageFit
"cover" | "contain"
"cover" fills edge to edge, cropped (default). "contain" insets art with its own margin.
imagePosition
string
object-position for the "cover" fit, e.g. "top". Default "center".
imageScale
number
Scales the photo within its "cover" fit. Under 1 zooms out a touch. Default 1.
badge
"online" | "away" | "busy" | "offline"
Small status dot on the bottom-right edge. Omit for none.
bordered
boolean
The tinted border stroke. Default true - AvatarGroup turns it off itself.
showTooltip
boolean
Names the avatar on hover, via Tooltip. Default true.
textClassName
string
Overrides the initial's color. Default "text-zinc-800 dark:text-zinc-200".

Props - AvatarGroup

PropTypeDescription
avatars
AvatarProps[]
Array of avatar objects.
max
number
Maximum avatars shown. Default 5.
size
AvatarSize
Size applied to all avatars. Default "default".
onAdd
() => void
Shows the + button; called on click.