# Avatar default
A shadcn/ui block from the [@craftui](https://www.craftui.space) registry, listed on [shadcn.exchange](https://shadcn.exchange/r/craftui/avatar-default).
- Page, with a live preview: https://shadcn.exchange/r/craftui/avatar-default
- Screenshot: https://abzjhwgwpdpz7ua5.public.blob.vercel-storage.com/shots/craftui/avatar-default-light-2aff72de8d3bf01d.png
- Registry item: https://www.craftui.space/r/avatar-default.json
- Listed: 2026-10-13, source last changed 2026-10-13
## Install
```bash
npx shadcn@latest add https://www.craftui.space/r/avatar-default.json
```
Run it in a project that has shadcn/ui set up. It adds the files below and installs what they depend on.
## Dependencies
- npm packages: `motion`
- Registry items: `https://www.craftui.space/r/craftui-base.json`
## Files
### `components/craftui/blocks/avatar/default.tsx`
```tsx
"use client";
import * as React from "react";
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
// ── Types ─────────────────────────────────────────────────────────────────────
export type AvatarMember = {
id: string;
name: string;
/** Role, read out as part of the tile's accessible name. */
role: string;
src: string;
/** 1-indexed [row, column] slot in the grid. */
cell: [number, number];
};
export interface AvatarGridProps {
members?: AvatarMember[];
/** Node rendered in the centre tile — a brand mark by default. */
logo?: React.ReactNode;
/** 1-indexed [row, column] of the centre tile. */
logoCell?: [number, number];
/** Grid size, in cells. */
rows?: number;
columns?: number;
/**
* CSS mask applied to the placeholder layer — a circular fade by default.
* Pass `false` to keep every shell at full strength.
*/
mask?: string | false;
/**
* Arbitrary tiles dropped into named cells — a "we're hiring" slot, say.
* They occupy their cell, so no placeholder shell is drawn underneath.
*/
extraTiles?: { cell: [number, number]; content: React.ReactNode }[];
/**
* Renders the active member's role as a pointer badge beside their tile.
* Off by default: standalone, the cluster is a picture of a team and the
* roles live in each tile's accessible name.
*/
roleBadges?: boolean;
/**
* Custom badge contents. Defaults to the member's role; pass this to put a
* name, a bio, anything the caller wants inside the same pill.
*/
renderBadge?: (member: AvatarMember) => React.ReactNode;
/** Member selected before anyone interacts. Null leaves the cluster at rest. */
defaultSelectedId?: string | null;
/**
* Controlled selection. Pass it and the caller owns which member is picked —
* the grid stops keeping its own copy, so a list outside the grid and the
* grid itself can't drift apart. Hover still previews on top of it.
*/
selectedId?: string | null;
/** Fires when a tile is clicked. Required to make `selectedId` do anything. */
onSelect?: (id: string) => void;
/**
* Fires whenever the active member changes — hover preview or committed
* click. Lets a caller render name, role and bio outside the grid without
* the grid having to know anything about how they are laid out.
*/
onActiveChange?: (id: string | null) => void;
className?: string;
}
// ── Default content ──────────────────────────────────────────────────────────
const DEFAULT_MEMBERS: AvatarMember[] = [
{
id: "maya",
name: "Maya Ellis",
role: "Admin",
src: "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=300&auto=format&fit=crop&q=80",
cell: [2, 2],
},
{
id: "noor",
name: "Noor Haddad",
role: "Designer",
src: "https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=300&auto=format&fit=crop&q=80",
cell: [2, 3],
},
{
id: "tom",
name: "Tom Brandt",
role: "Engineer",
src: "https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=300&auto=format&fit=crop&q=80",
cell: [3, 2],
},
{
id: "amir",
name: "Amir Rahal",
role: "Support Lead",
src: "https://images.unsplash.com/photo-1519085360753-af0119f7cbe7?w=300&auto=format&fit=crop&q=80",
cell: [3, 4],
},
{
id: "dev",
name: "Dev Sharma",
role: "Developer",
src: "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=300&auto=format&fit=crop&q=80",
cell: [4, 3],
},
{
id: "lena",
name: "Lena Fischer",
role: "Content Reviewer",
src: "https://images.unsplash.com/photo-1531123897727-8f129e1688ce?w=300&auto=format&fit=crop&q=80",
cell: [4, 4],
},
];
/**
* The mark's ink spans 12.5 units of the 24-unit viewBox, so the original
* x-offsets left it optically shifted toward the left edge of its tile. Fixed
* in the path itself rather than with a nudge in the component, so the icon
* stays centred wherever it is used.
*/
const DEFAULT_LOGO = (
);
/**
* Shared so the placeholder layer and the avatar grid never drift apart. Steps
* down on small screens: five columns of gutter is the one place where a phone
* can win a few pixels per tile back without changing the layout.
*/
const GRID_GAP = "gap-1.5 sm:gap-2 md:gap-3";
// ── Motion ────────────────────────────────────────────────────────────────────
/** Hover lift and press. Bounce 0 — overshoot would read as toy-like here. */
const SPRING = { type: "spring", duration: 0.3, bounce: 0 } as const;
/** ease-out-quart. Strong enough that 250ms still lands as "instant". */
const EASE_ENTRANCE = [0.165, 0.84, 0.44, 1] as const;
/** ease-out-quad. Fades and small badge travel — a fade should read as a fade. */
const EASE_FADE = [0.25, 0.46, 0.45, 0.94] as const;
const ENTRANCE_DURATION = 0.25;
/** Gap between rings. Below ~40ms the wave stops reading; above ~80ms it drags. */
const RING_STAGGER = 0.06;
/**
* How far the unselected faces step back once someone is active. 0.5 is enough
* to make the active face the only thing the eye lands on; below ~0.4 the rest
* of the team stops reading as present at all, which is the wrong message for
* a group portrait.
*/
const DIM_OPACITY = 0.5;
/**
* Circular fade: the shells nearest the cluster read at full strength, then
* fall away to nothing before the grid's corners — which is what keeps the
* block from looking like it was cropped out of a larger board.
*/
const DEFAULT_MASK =
"radial-gradient(circle at 50% 50%, oklch(0 0 0) 32%, oklch(0 0 0 / 0.55) 52%, oklch(0 0 0 / 0.15) 68%, transparent 80%)";
// ── Empty tiles ───────────────────────────────────────────────────────────────
/**
* The empty slots are the backdrop, not content — they are generated from the
* grid dimensions rather than listed, so changing `rows`/`columns` fills the
* board without touching any data.
*/
function EmptyTile({ cell }: { cell: [number, number] }) {
return (
);
}
// ── Role badge ────────────────────────────────────────────────────────────────
/**
* The active member's role, on a pointer pill anchored to their tile. It sits
* outside the tile and is `pointer-events-none`, so it can never intercept the
* hover that summoned it — a badge that eats its own trigger flickers forever.
*
* Entering, so ease-out; the arrow and pill share one transform, because two
* halves of one badge arriving on different timings reads as a glitch.
*/
function RoleBadge({
member,
renderBadge,
side,
reduceMotion,
}: {
member: AvatarMember;
renderBadge?: (member: AvatarMember) => React.ReactNode;
side: "left" | "right";
reduceMotion: boolean | null;
}) {
const content = renderBadge ? renderBadge(member) : member.role;
const isLeft = side === "left";
const offset = isLeft ? 8 : -8;
return (
{/* Cursor arrow, tucked into the corner nearest the tile it points at */}
{content}
);
}
// ── Root ──────────────────────────────────────────────────────────────────────
export default function AvatarGrid({
members = DEFAULT_MEMBERS,
logo = DEFAULT_LOGO,
logoCell = [3, 3],
rows = 5,
columns = 5,
mask = DEFAULT_MASK,
extraTiles = [],
roleBadges = false,
renderBadge,
defaultSelectedId = null,
selectedId: selectedIdProp,
onSelect,
onActiveChange,
className,
}: AvatarGridProps = {}) {
const scopeId = React.useId().replace(/:/g, "");
const reduceMotion = useReducedMotion();
// Split state, the same way contact-reveal-card does it: hover is a preview,
// click commits. Without the committed half there is no way to pick a member
// on a touch device, where hover doesn't exist.
const [uncontrolledSelectedId, setUncontrolledSelectedId] = React.useState<
string | null
>(defaultSelectedId);
// Controlled when the prop is passed at all — including as null, which is a
// caller saying "nothing is selected", not "you decide".
const isControlled = selectedIdProp !== undefined;
const selectedId = isControlled ? selectedIdProp : uncontrolledSelectedId;
const [hoveredId, setHoveredId] = React.useState(null);
const activeId = hoveredId ?? selectedId;
const select = (id: string) => {
if (!isControlled) setUncontrolledSelectedId(id);
onSelect?.(id);
};
// Held in a ref, and kept current in its own effect rather than during
// render, so a caller passing an inline arrow function doesn't re-fire the
// callback on every render.
const onActiveChangeRef = React.useRef(onActiveChange);
React.useEffect(() => {
onActiveChangeRef.current = onActiveChange;
});
React.useEffect(() => {
onActiveChangeRef.current?.(activeId);
}, [activeId]);
/**
* Reduced motion keeps the fade and drops the scale — the entrance still
* explains that the cluster is built outward from the mark, it just stops
* moving to say so. Same for the hover lift and the press, handled below.
*/
const enter = {
initial: reduceMotion
? { opacity: 0 }
: // 0.95, never 0 — nothing appears from nothing.
{ opacity: 0, scale: 0.95 },
animate: reduceMotion ? { opacity: 1 } : { opacity: 1, scale: 1 },
transition: (rank: number) => ({
duration: ENTRANCE_DURATION,
ease: EASE_ENTRANCE,
delay: rank * RING_STAGGER,
}),
};
/**
* Tiles are grouped into rings by their distance from the mark, so members
* equidistant from the centre arrive together and the entrance reads as a
* wave outward rather than as six unrelated fades. Ranking by list order
* instead would stagger by nothing the eye can see.
*/
const ringRank = React.useMemo(() => {
const distance = (cell: [number, number]) =>
Math.round(
Math.hypot(cell[0] - logoCell[0], cell[1] - logoCell[1]) * 100,
) / 100;
const rings = Array.from(
new Set(members.map((member) => distance(member.cell))),
).sort((a, b) => a - b);
return new Map(
members.map((member) => [
member.id,
// +1 leaves rank 0 to the brand mark at the centre.
rings.indexOf(distance(member.cell)) + 1,
]),
);
}, [members, logoCell]);
// Both layers must resolve to identical tracks or the shells drift off the
// grid the avatars sit on.
const gridTemplate: React.CSSProperties = {
gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
gridTemplateRows: `repeat(${rows}, minmax(0, 1fr))`,
};
const occupied = React.useMemo(() => {
const taken = new Set([`${logoCell[0]}-${logoCell[1]}`]);
for (const member of members) taken.add(`${member.cell[0]}-${member.cell[1]}`);
for (const tile of extraTiles) taken.add(`${tile.cell[0]}-${tile.cell[1]}`);
return taken;
}, [members, logoCell, extraTiles]);
const emptyCells = React.useMemo(() => {
const cells: Array<[number, number]> = [];
for (let row = 1; row <= rows; row++) {
for (let column = 1; column <= columns; column++) {
if (!occupied.has(`${row}-${column}`)) cells.push([row, column]);
}
}
return cells;
}, [rows, columns, occupied]);
return (
setHoveredId(null)}
>
{/*
Depth is a layered box-shadow, not a border: the ring layer reads as
the 1px edge while the two soft layers do the lift, and because every
layer is transparent it holds up over any background the block is
dropped onto. Dark mode collapses to a single white ring — soft black
depth layers are invisible on a dark surface. Written as a scoped
style block because a three-layer shadow with commas doesn't survive
Tailwind's arbitrary-value syntax cleanly.
*/}
{/*
Placeholder shells live on their own layer so the radial mask can fade
them out towards the edges without touching the avatars stacked above
— masking the whole grid would dim the outer cards with them. The
layer mirrors the parent's tracks and gap exactly, so the shells stay
on the same grid they would have occupied inline.
*/}
{emptyCells.map(([row, column]) => (
))}
{/* Brand mark — same tile geometry as an avatar, so the cluster stays
on grid. Rank 0 of the entrance: the cluster is built around it, so
it is the thing the eye should be given first. */}
{logo}
{extraTiles.map((tile) => (
{tile.content}
))}
{members.map((member) => {
const isActive = activeId === member.id;
return (
// Two layers on purpose: the outer one owns the entrance, the
// inner one owns hover and press. Sharing a single element would
// mean one `transition` serving a delayed tween and an
// interruptible spring at once, and the entrance delay would leak
// into every hover.
{
if (event.pointerType === "mouse") setHoveredId(member.id);
}}
onPointerLeave={(event) => {
if (event.pointerType === "mouse") setHoveredId(null);
}}
onFocusCapture={() => setHoveredId(member.id)}
onBlurCapture={() => setHoveredId(null)}
animate={{ scale: reduceMotion ? 1 : isActive ? 1.03 : 1 }}
// Press wins over the hover lift — Motion gives gesture props
// priority over `animate`, so the two never fight.
whileTap={reduceMotion ? undefined : { scale: 0.96 }}
transition={SPRING}
>
{/* Outside the hover layer on purpose: nested in it, the badge
would inherit the 1.08 lift and its text would scale with the
photo. Side follows the tile's column so a badge on a
left-hand tile points inward, never off the grid. */}
{roleBadges && isActive && (
)}
);
})}