RadCN
Displayreadycomponentready

Avatar

A dependency-free avatar primitive for image-backed identities, fallbacks, badges, and stacked groups.

Importimport { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from 'radcn/avatar'
Preview

Live package example

Render the upstream Avatar demo with exact GitHub image URLs, alt text, fallbacks, rounded-square styling, and a stacked grayscale group.

Avatar Demo

Render the upstream Avatar demo with exact GitHub image URLs, alt text, fallbacks, rounded-square styling, and a stacked grayscale group.

Preview
@shadcn@evilrabbit
@shadcn@maxleiter@evilrabbit

Remote GitHub avatar images are app-owned content; RadCN owns the Avatar, Image, Fallback, and Group hooks plus class/style customization.

import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from 'radcn/avatar'

export function AvatarDemo() {
  return (
    <div class="flex flex-row flex-wrap items-center gap-12">
      <Avatar>
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback ariaHidden={true}>CN</AvatarFallback>
      </Avatar>
      <Avatar class="rounded-lg" style="border-radius:var(--radcn-radius);">
        <AvatarImage src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
        <AvatarFallback ariaHidden={true}>ER</AvatarFallback>
      </Avatar>
      <AvatarGroup
        ariaLabel="RadCN contributors"
        class="flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background *:data-[slot=avatar]:grayscale"
      >
        <Avatar style="box-shadow:0 0 0 2px var(--radcn-background);">
          <AvatarImage
            src="https://github.com/shadcn.png"
            alt="@shadcn"
            class="grayscale"
            style="filter:grayscale(1);"
          />
          <AvatarFallback ariaHidden={true}>CN</AvatarFallback>
        </Avatar>
        <Avatar style="margin-left:-0.5rem;box-shadow:0 0 0 2px var(--radcn-background);">
          <AvatarImage
            src="https://github.com/maxleiter.png"
            alt="@maxleiter"
            class="grayscale"
            style="filter:grayscale(1);"
          />
          <AvatarFallback ariaHidden={true}>LR</AvatarFallback>
        </Avatar>
        <Avatar style="margin-left:-0.5rem;box-shadow:0 0 0 2px var(--radcn-background);">
          <AvatarImage
            src="https://github.com/evilrabbit.png"
            alt="@evilrabbit"
            class="grayscale"
            style="filter:grayscale(1);"
          />
          <AvatarFallback ariaHidden={true}>ER</AvatarFallback>
        </Avatar>
      </AvatarGroup>
    </div>
  )
}

Installation

Intended future install command. RadCN is private and not published to npm yet, so this snippet documents the target user-facing API rather than something external consumers can run today.

pnpm add radcn # intended future package
import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from 'radcn/avatar'

Theming

RadCN tokens read the resolved theme from the document. Store the user's preference separately, then resolve system preferences to a concrete light or dark theme before setting package tokens.

<html data-radcn-theme-mode="system" data-radcn-theme="dark">
  ...
</html>

Accessibility

  • Meaningful image-backed avatars keep their accessible names on native img alt attributes.
  • Fallback initials remain in the DOM for visual backup and can be aria-hidden when an image alt already names the person.
  • AvatarGroup can receive an ariaLabel when the stacked set needs a group label in application context.
  • Avatar exposes data-radcn-avatar, AvatarImage exposes data-radcn-avatar-image, AvatarFallback exposes data-radcn-avatar-fallback, and AvatarGroup exposes data-radcn-avatar-group for stable tests and composition.

Customization

  • Default Avatar shape is circular through package CSS, matching the first upstream avatar.
  • The upstream rounded-lg Avatar maps to class plus style or CSS variables on the Avatar root; no package-specific shape prop is required.
  • Stacked negative spacing and ring treatment map to AvatarGroup package CSS and public class/style hooks.
  • Grayscale image treatment maps to app-owned class/style on AvatarImage, while image URLs, loading strategy, and hosting remain app-owned content.
  • Custom tokens remain available through package CSS variables such as --radcn-avatar-bg, --radcn-avatar-fg, --radcn-avatar-border, and --radcn-avatar-size.

Remix 3 Notes

  • React client component markers and Radix Avatar primitives map to dependency-free native img and span/div markup.
  • data-slot="avatar", data-slot="avatar-image", and data-slot="avatar-fallback" map to data-radcn-avatar, data-radcn-avatar-image, and data-radcn-avatar-fallback.
  • data-size maps to RadCN data-size plus size classes, while className maps to class and cn maps to explicit class composition.
  • Tailwind flex, flex-row, flex-wrap, items-center, gap-12, rounded-lg, -space-x-2, ring, ring-background, and grayscale utilities map to RadCN package CSS, class, style, CSS variables, and docs/app CSS.
  • Remote GitHub avatar images are content choices and are tested by stable attributes rather than network image decoding.
  • AvatarBadge and AvatarGroupCount are package capabilities, but they are not required by the direct avatar-demo example.
  • Vendor source remains read-only evidence and is not imported by RadCN.