Avatar

Visual representation of a user or entity via image, initials, or fallback icon.

stable
since v0.1.0
1.56 kB
feedback
identity
user

Preview

tsx

import { Avatar } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <Avatar name="Jane Doe" />;
}

With image

Provide an src to render an <img>. When the image fails or is still loading, Avatar gracefully falls back to initials derived from name.

Preview

Open

tsx

import { Avatar } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <Avatar name="Ada Lovelace" src="https://i.pravatar.cc/120?img=47" />;
}

Sizes

Avatar ships six sizes — xs, sm, md (default), lg, xl, and 2xl.

Preview

Open

tsx

import { Avatar } from '@arshad-shah/cynosure-react';

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

Shapes

Pick between circle (default), rounded, and square shapes.

Preview

Open

tsx

import { Avatar } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem', alignItems: 'center' }}>
      <Avatar name="Jane Doe" shape="circle" />
      <Avatar name="Jane Doe" shape="rounded" />
      <Avatar name="Jane Doe" shape="square" />
    </div>
  );
}

Initials and color

When src is missing, Avatar shows the initials derived from name. A deterministic colour from the built-in palette is auto-selected per name; override with colorScheme (red, amber, green, blue, violet, pink, teal, orange).

Preview

Open

tsx

import { Avatar } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem', alignItems: 'center' }}>
      <Avatar name="Ada Lovelace" />
      <Avatar name="Grace Hopper" />
      <Avatar name="Linus Torvalds" />
      <Avatar name="Margaret Hamilton" />
      <Avatar name="Donald Knuth" colorScheme="violet" />
      <Avatar initials="?" colorScheme="teal" />
    </div>
  );
}

Status indicator

Pass status (online, offline, away, busy) to render a presence dot. Use statusPosition to anchor it to bottom-right (default) or top-right.

Preview

Open

tsx

import { Avatar } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem', alignItems: 'center' }}>
      <Avatar name="Jane Doe" status="online" />
      <Avatar name="John Smith" status="away" />
      <Avatar name="Sam Chen" status="busy" />
      <Avatar name="Ada Lovelace" status="offline" />
      <Avatar name="Grace Hopper" status="online" statusPosition="top-right" />
    </div>
  );
}

Ring

Set ring to add a tokenised ring around the avatar — useful for stacked groups or highlighting the current user.

Preview

Open

tsx

import { Avatar } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem', alignItems: 'center' }}>
      <Avatar name="Jane Doe" ring />
      <Avatar name="John Smith" ring size="lg" />
      <Avatar name="Ada Lovelace" ring src="https://i.pravatar.cc/120?img=12" size="xl" />
    </div>
  );
}

API

PropTypeDefaultDescription

src

string

—

Image source URL. When omitted or failed to load, the fallback renders.

name

string

—

User's display name, used to derive initials and a deterministic colour.

alt

string

—

`alt` text for the image; falls back to `name`.

fallback

ReactNode

—

Custom fallback node rendered when the image is unavailable.

icon

ReactNode

—

Icon shown when neither image nor initials are available.

size

"xs"|"sm"|"md"|"lg"|"xl"|"2xl"

"md"

Pixel scale. One of `xs`, `sm`, `md`, `lg`, `xl`, `2xl`.

shape

"circle"|"square"|"rounded"

"circle"

Outline shape. One of `circle`, `square`, `rounded`.

colorScheme

—

Palette token for the fallback background. When omitted, a colour is derived deterministically from `name`.

status

"online"|"offline"|"away"|"busy"

—

Presence indicator. One of `online`, `offline`, `away`, `busy`.

statusPosition

"top-right"|"bottom-right"

"bottom-right"

Where the presence dot sits relative to the avatar.

ring

boolean

false

Render a halo ring around the avatar; useful for stacking in groups.

initials

string

—

Overrides the initials derived from `name`.

Accessibility

Provide a name so initials and alt text stay meaningful when the image is missing.
When the avatar is purely decorative, leave name empty and add aria-hidden="true" on the wrapping element.
Status dots render with aria-hidden="true" — pair them with an off-screen label or adjacent text when status conveys meaning.
The fallback waits 400ms before swapping in initials so users on fast networks see the image first.
Initials are rendered inside a fallback element which exposes an aria-label when only a name (no derived initials) is available.

Recipes

Combine src with name so initials are ready as a graceful fallback.
Use ring on the current user’s avatar to disambiguate them in a roster.
Override colorScheme only when brand colour matters — the deterministic palette keeps an avatar’s colour stable across renders.
Compose multiple avatars inside <AvatarGroup> to represent collaborators with optional overflow.