Avatar

(no submodules)

- avatar.variants — `avatarVariants` is the cva confi…

avatar.variants — avatarVariants is the cva config that powers the <Avatar> chassis component (<AvatarImage> and <AvatarFallback>…
avatar.variants — avatarVariants is the cva confi…
avatar.variants — avatarVariants is the cva config that powers the <Avatar> chassis component (<AvatarImage> and <AvatarFallback>…
avatar.variants — avatarVariants is the cva confi…
avatar.variants — avatarVariants is the cva config that powers the <Avatar> chassis component (<AvatarImage> and <AvatarFallback>…
avatar.variants — avatarVariants is the cva confi…
avatar.variants — avatarVariants is the cva config that powers the <Avatar> chassis component (<AvatarImage> and <AvatarFallback>…
avatar.variants — avatarVariants is the cva config that powers the <Avatar> chassis component (<AvatarImage> and <AvatarFallback>…

Purpose

<Avatar> is the chassis circular image holder built on @radix-ui/react-avatar. It ships as a family of three components — <Avatar> (root), <AvatarImage>, <AvatarFallback> — that compose into the conventional shadcn avatar pattern. Per the shadcn skill rule, ALWAYS pair an <AvatarImage> with an <AvatarFallback> — Radix swaps the fallback in when the image source fails to load OR when no source is supplied. An Avatar without a fallback flashes empty while loading, then disappears silently on a 404 — both are bugs.

The root <Avatar> exposes a size axis with four rungs (sm / default / lg / xl) using Tailwind's size-* shorthand so width and height stay in lockstep, preventing off-by-one ratio bugs that arise when consumers set width and height independently.

Features

Four sizes via the size axis (sm / default / lg / xl) using Tailwind size-*.
Three composition primitives — Avatar (root), AvatarImage, AvatarFallback.
Radix-managed image-loading state machine — <AvatarFallback> swaps in automatically when the image source fails or has not yet loaded.
aspect-square object-cover on <AvatarImage> so portrait / landscape sources crop centrally rather than distorting.
Forwards refs to the underlying Radix elements on every sub-component.

Usage: Basic Example

import { Avatar, AvatarFallback, AvatarImage } from "@suaveplan/react-ui";

export function UserAvatar() {
    return (
        <Avatar>
            <AvatarImage src="/avatar.png" alt="Jane Doe" />
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
    );
}

Usage: Advanced Example

import { Avatar, AvatarFallback, AvatarImage } from "@suaveplan/react-ui";

interface AvatarStackUser {
    readonly id: string;
    readonly name: string;
    readonly avatarUrl?: string;
}

export function AvatarStack({ users }: { users: AvatarStackUser[] }) {
    return (
        <div className="flex -space-x-2">
            {users.slice(0, 3).map((user) => (
                <Avatar key={user.id} size="lg" className="border-2 border-background">
                    {user.avatarUrl != null ? (
                        <AvatarImage src={user.avatarUrl} alt={user.name} />
                    ) : null}
                    <AvatarFallback>
                        {user.name
                            .split(" ")
                            .slice(0, 2)
                            .map((part) => part[0])
                            .join("")}
                    </AvatarFallback>
                </Avatar>
            ))}
        </div>
    );
}

API Reference

`<Avatar>`

forwardRef<…, AvatarProps> — root container backed by @radix-ui/react-avatar Root.

Prop	Type	Default	Description
`size`	`"sm" \| "default" \| "lg" \| "xl"`	`"default"`	Diameter — uses Tailwind `size-*`.
Radix props	Radix-typed	—	All `AvatarPrimitive.Root` props.

`<AvatarImage>`

forwardRef<…, AvatarImageProps> — image source. Cover-fits inside the circular surface. Radix swaps in <AvatarFallback> automatically when the source fails to load.

`<AvatarFallback>`

forwardRef<…, AvatarFallbackProps> — fallback surface. Per shadcn skill rule, REQUIRED in every Avatar. Typical contents are user initials (one or two letters) or an icon.

Errors

The Avatar components do NOT call useTranslation() so they do not interact with the i18n provider. The image's alt attribute and the fallback content are consumer-provided; consumers wanting translated alt text should pass t('user.avatar.alt') at the call site.

Implementation Notes

size-* is used at the root so width and height change together — the historical bug where consumers passed w-10 h-12 and produced an ellipse cannot occur with this API.
Radix manages the image-loading state machine: <AvatarImage> is hidden until the image loads successfully, and <AvatarFallback> is shown until the image is confirmed loaded. Without a fallback, the avatar surface is empty during the load window and after a load failure.
<AvatarFallback> accepts an optional delayMs prop (forwarded from Radix) — when set, the fallback is suppressed for that many ms so quick image loads don't cause a brief fallback flash.
The chassis does NOT ship an AvatarGroup component — that pattern is consumer composition (<div className="flex -space-x-2">…</div> over a list of <Avatar>s) and shipping it as a discrete primitive forecloses the many layout variations consumers want.
All sub-components forward refs to the underlying Radix elements so consumers can attach event listeners, focus management, or animation controls without wrapping.

5.8 KiB Raw Blame History