Avatar Variants

Purpose

avatarVariants is the cva config that powers the <Avatar> chassis component (<AvatarImage> and <AvatarFallback> ride alongside as sub-component cvas). 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 — this prevents the off-by-one ratio bugs that arise when consumers set width and height independently.

Features

Single size axis with four rungs (sm 32px, default 40px, lg 48px, xl 64px) using Tailwind size-*.
rounded-full applied at the root so the surface is always circular regardless of children.
overflow-hidden clips images that would otherwise leak past the circular edge.
<AvatarImage> uses aspect-square h-full w-full object-cover so portrait / landscape sources crop centrally.
<AvatarFallback> uses bg-muted text-muted-foreground with uppercase tracking-wider so user initials read clearly.

Usage: Basic Example

import { avatarVariants } from "@suaveplan/react-ui";

const small = avatarVariants({ size: "sm" });
const default_ = avatarVariants();
const xl = avatarVariants({ size: "xl" });

Usage: Advanced Example

import { cva } from "class-variance-authority";
import { avatarVariants } from "@suaveplan/react-ui";

const ringedAvatar = cva(
    [avatarVariants({ size: "lg" }), "ring-2 ring-primary ring-offset-2"].join(
        " "
    )
);

API Reference

`avatarVariants(opts?)`

Option	Type	Default	Description
`size`	`"sm" \| "default" \| "lg" \| "xl"`	`"default"`	Diameter — uses Tailwind `size-*` to set width and height together.

`avatarImageVariants()`, `avatarFallbackVariants()`

No options — single canonical class strings.

Implementation Notes

The chassis uses size-* (Tailwind 3.4+) rather than separate w-* / h-* classes so the avatar's diameter changes in lockstep with the image dimension. This avoids the historical bug where consumers set w-10 h-12 and produced an ellipse instead of a circle.
AvatarFallback's bg-muted background reads as a low-contrast surface that does not compete with the image; the muted-foreground initials are scaled at text-sm so even the xl size renders the initials at a comfortable read size.
The relative positioning on the root container is required by Radix's image-loading state machine — Radix toggles <AvatarImage> opacity via inline styles that depend on the parent's positioning context.
shrink-0 on the root prevents the avatar from shrinking inside flex parents (e.g. inside an <AvatarGroup> row or a list item with limited horizontal space).

2.7 KiB Raw Permalink Blame History