Avatar

An image standing in for a person, with a fallback that always renders. Initials are derived from the name, and a broken image falls through to them.

src/components/ui/avatar.tsx

About

From the component's own source, where it was written.

An image standing in for a person, with a fallback that always renders.

The image is swapped out on error rather than left broken, and initials are derived from name so a caller does not have to compute them.

Install

npx astralyx-ui add avatar

Usage

import { Avatar } from '@/components/ui/avatar'

<Avatar src={user.photo} name="Ada Lovelace" />

Composer

Change the props and the source below follows.

Props

size

shape

name

src

tsx

<Avatar name="Ada Lovelace" />

Examples

Badges and positions

tsx

<AvatarWithBadge>
  <Avatar name="Ada Lovelace" />
  <AvatarBadge tone="online" label="Online" />
</AvatarWithBadge>

<AvatarWithBadge>
  <Avatar name="Grace Hopper" />
  <AvatarBadge position="tr" tone="primary">3</AvatarBadge>
</AvatarWithBadge>

Sizes

tsx

<Avatar size="xs" name="Ada Lovelace" />
<Avatar size="xl" name="Ada Lovelace" />

Image, fallback, and a broken URL

tsx

<Avatar src={photo} name="Ada Lovelace" />
<Avatar name="Grace Hopper" />
<Avatar src="/missing.png" name="Alan Turing" />

Shapes

tsx

<Avatar shape="circle" name="Ada Lovelace" />
<Avatar shape="rounded" name="Ada Lovelace" />

Group

tsx

<AvatarGroup max={3}>
  <Avatar name="Ada Lovelace" />
  <Avatar name="Grace Hopper" />
  <Avatar name="Alan Turing" />
  <Avatar name="Katherine Johnson" />
</AvatarGroup>

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`Avatar`

Extends Omit<ComponentProps<'span'>, 'children'>.

Prop	Type	Default	Description
size	'sm' \| 'default' \| 'xs' \| 'lg' \| 'xl'	'default'	Footprint, with the initials scaled to match.
shape	'circle' \| 'rounded'	'circle'	Circle, or the kit squircle.
src	string	—	Image URL. On a load error the component falls back to initials instead of showing a broken image.
name	string	—	Alt text, and the source of the derived initials. "Ada Lovelace" becomes "AL".
fallback	ReactNode	—	Overrides the derived initials.

`AvatarGroup`

Overlapping row of avatars.

Extends ComponentProps<'div'>.

Prop	Type	Default	Description
max	number	—	Show this many, then a +N chip for the rest.
size	VariantProps<typeof avatarVariants>['size']	'default'	Footprint, with the initials scaled to match.

`AvatarBadge`

Extends ComponentProps<'span'>.

Prop	Type	Default	Description
position	AvatarBadgePosition \| keyof typeof POSITION_ALIAS	'bottom-right'	Corner to pin to. The short forms `tr`, `tl`, `br` and `bl` are accepted too.
size	keyof typeof BADGE_SIZE	'default'	Footprint, with the initials scaled to match.
tone	keyof typeof BADGE_TONE	'online'	Presence colour, or a filled chip when the badge carries content.
ring	boolean	true	Ring in the surface colour. Not decoration — a dot the same colour as what sits behind it disappears.
label	string	—	Accessible name. Without one a bare status dot is announced as nothing, so it is marked aria-hidden instead.

`AvatarWithBadge`

The positioning wrapper. Avatar clips its own overflow to round the image, so a badge inside it would be cut off at exactly the corner it sits on.

Extends ComponentProps<'span'>.

Functions

Function	Signature	Description
avatarVariants	(props?: { size?: 'sm' \| 'default' \| 'xs' \| 'lg' \| 'xl'; shape?: 'circle' \| 'rounded' }) => string	An image standing in for a person, with a fallback that always renders.

Types

Type	Definition	Description
`AvatarBadgePosition`	'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'	A marker pinned to a corner of an Avatar — presence, a count, a small icon.