Core components / Avatars
Avatar
A person, team or app. Initials when there's no photo, and while one loads. Circle for people, square for workspaces and apps; the corner holds a status dot, a workspace mark or a verified tick. Avatar group overlaps up to a few people, then a +N count, and Add avatar ends a group with a button that adds someone.
Code
The component itself, ready to drop into your project. Switch between React, Vue and plain HTML; every version uses the same Tailwind classes on Ochre's tokens.
"use client";
import * as React from "react";
import { cx } from "@/components/ochre/utils";
export type AvatarSize = "xs" | "s" | "m" | "l" | "xl" | "2xl";
export type AvatarStatus = "online" | "away" | "busy" | "offline";
export type AvatarProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
name: string;
src?: string;
size?: AvatarSize;
shape?: "circle" | "square";
status?: AvatarStatus;
icon?: React.ReactNode;
// A small ink square in the corner: the workspace a person belongs to, or the app that acted for them.
mark?: React.ReactNode;
// A verified tick in the corner, for confirmed people and organisations.
verified?: boolean;
};
const sizes: Record<
AvatarSize,
{ box: string; text: string; square: string; dot: string; mark: string; tick: string }
> = {
xs: { box: "size-6", text: "text-[12px]", square: "rounded-6", dot: "size-1.5", mark: "-bottom-0.5 -right-0.5 size-3 text-[8px]", tick: "-bottom-0.5 -right-0.5 size-3 [&_svg]:size-2.5" },
s: { box: "size-7", text: "text-[12px]", square: "rounded-6", dot: "size-2", mark: "-bottom-0.5 -right-0.5 size-3 text-[8px]", tick: "-bottom-0.5 -right-0.5 size-3 [&_svg]:size-2.5" },
m: { box: "size-8", text: "text-[13px]", square: "rounded-8", dot: "size-2", mark: "-bottom-1 -right-1 size-3.5 text-[10px]", tick: "-bottom-0.5 -right-0.5 size-3.5 [&_svg]:size-3" },
l: { box: "size-10", text: "text-[16px]", square: "rounded-10", dot: "size-2.5", mark: "-bottom-1 -right-1 size-4 text-[11px]", tick: "-bottom-0.5 -right-0.5 size-4 [&_svg]:size-3.5" },
xl: { box: "size-12", text: "text-[18px]", square: "rounded-12", dot: "size-3", mark: "-bottom-1 -right-1 size-5 text-[11px]", tick: "-bottom-0.5 -right-0.5 size-[18px] [&_svg]:size-4" },
"2xl": { box: "size-16", text: "text-[24px]", square: "rounded-16", dot: "size-3.5", mark: "-bottom-1 -right-1 size-6 text-[13px]", tick: "-bottom-0.5 -right-0.5 size-[22px] [&_svg]:size-5" },
};
const statuses: Record<AvatarStatus, string> = {
online: "bg-icon-success",
away: "bg-icon-warning",
busy: "bg-icon-danger",
offline: "bg-icon-subtle",
};
export function initials(name: string) {
const parts = name.trim().split(/\s+/).filter(Boolean);
const first = parts[0]?.[0] ?? "";
const last = parts.length > 1 ? parts[parts.length - 1][0] : (parts[0]?.[1] ?? "");
return (first + last).toUpperCase();
}
// The verified tick: a filled badge in the accent with the check cut out in the icon-on-accent colour.
export function VerifiedTick() {
return (
<svg viewBox="0 0 24 24" aria-hidden="true">
<path
className="fill-icon-accent"
d="M3.85 8.62a4 4 0 0 1 4.78-4.77 4 4 0 0 1 6.74 0 4 4 0 0 1 4.78 4.78 4 4 0 0 1 0 6.74 4 4 0 0 1-4.77 4.78 4 4 0 0 1-6.75 0 4 4 0 0 1-4.78-4.77 4 4 0 0 1 0-6.76Z"
/>
<path className="stroke-icon-on-accent" d="m9 12 2 2 4-4" fill="none" strokeWidth="2.25" strokeLinecap="round" strokeLinejoin="round" />
</svg>
);
}
// A person, team or app. Circle for people, square for workspaces and apps.
// Initials show while the photo loads, the photo fades in over them, and they stay if it fails.
// One thing sits in the corner at a time: a mark, else the verified tick, else the status dot.
export function Avatar({
name,
src,
size = "m",
shape = "circle",
status,
icon,
mark,
verified = false,
className,
...rest
}: AvatarProps) {
const [failed, setFailed] = React.useState(false);
const [loaded, setLoaded] = React.useState(false);
const img = React.useRef<HTMLImageElement>(null);
React.useEffect(() => {
setFailed(false);
setLoaded(Boolean(img.current?.complete && img.current.naturalWidth));
}, [src]);
const s = sizes[size];
const radius = shape === "circle" ? "rounded-full" : s.square;
const showImage = src && !failed;
const corner = mark != null ? "mark" : verified ? "verified" : status ? "status" : null;
return (
<span {...rest} className={cx("relative inline-flex shrink-0", s.box, className)}>
<span
role="img"
aria-label={verified ? `${name}, verified` : name}
className={cx(
"relative flex size-full select-none items-center justify-center overflow-hidden font-semibold leading-none",
radius,
icon && !showImage ? "bg-placeholder-bg text-placeholder-mark [&_svg]:size-1/2" : "bg-surface-strong text-text-default",
s.text,
)}
>
{icon && !showImage ? icon : <span aria-hidden="true">{initials(name)}</span>}
{showImage ? (
<img
ref={img}
src={src}
alt=""
onLoad={() => setLoaded(true)}
onError={() => setFailed(true)}
className={cx(
"absolute inset-0 size-full object-cover transition-[opacity,scale] duration-[var(--motion-slow)] ease-[var(--motion-ease-out)]",
loaded ? "scale-100 opacity-100" : "scale-105 opacity-0",
)}
/>
) : null}
</span>
{corner === "mark" ? (
<span
aria-hidden="true"
className={cx(
"absolute grid place-items-center overflow-hidden rounded-4 bg-action-ink font-mono font-medium leading-none text-action-on-ink ring-2 ring-surface-card [&_img]:size-full [&_img]:object-cover [&_svg]:size-2/3",
s.mark,
)}
>
{mark}
</span>
) : null}
{corner === "verified" ? (
<span aria-hidden="true" className={cx("absolute grid place-items-center rounded-full bg-surface-card", s.tick)}>
<VerifiedTick />
</span>
) : null}
{corner === "status" && status ? (
<span
aria-label={status}
className={cx(
"absolute bottom-0 right-0 rounded-full ring-2 ring-surface-card transition-colors duration-[var(--motion-base)]",
shape === "square" && "-bottom-0.5 -right-0.5",
s.dot,
statuses[status],
)}
/>
) : null}
</span>
);
}
export type AddAvatarSize = "s" | "m" | "l";
export type AddAvatarProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
size?: AddAvatarSize;
};
// 24, 32 or 40 pixels, with a 12, 16 or 16 pixel plus.
const addSizes: Record<AddAvatarSize, string> = {
s: "size-6 [&_svg]:size-3",
m: "size-8 [&_svg]:size-4",
l: "size-10 [&_svg]:size-4",
};
const addClasses =
"group/add inline-flex shrink-0 items-center justify-center rounded-full border border-border-strong bg-transparent text-icon-muted outline-none transition-ui press hover:border-border-accent hover:bg-status-accent-bg hover:text-icon-accent focus-visible:shadow-focus disabled:pointer-events-none disabled:opacity-50";
function PlusGlyph() {
return (
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden="true" className="transition-ui group-hover/add:rotate-90">
<path d="M12 5v14M5 12h14" />
</svg>
);
}
// An empty avatar-sized button that adds a person, at the end of a group or a member list.
// On hover it tints with the accent and the plus turns a quarter on the snappy spring.
export function AddAvatar({ size = "m", className, "aria-label": label = "Add person", ...rest }: AddAvatarProps) {
return (
<button type="button" aria-label={label} {...rest} className={cx(addClasses, addSizes[size], className)}>
<PlusGlyph />
</button>
);
}
export type AvatarGroupProps = React.HTMLAttributes<HTMLDivElement> & {
people: { name: string; src?: string }[];
max?: number;
size?: "s" | "m" | "l";
// Adds an Add avatar button after the group.
onAdd?: () => void;
addLabel?: string;
};
const groupSizes = {
s: { avatar: "xs" as const, overlap: "-ml-[5px] group-hover/avatars:-ml-0.5", more: "size-6 text-[12px]", add: "size-6 [&_svg]:size-3" },
m: { avatar: "s" as const, overlap: "-ml-1.5 group-hover/avatars:-ml-0.5", more: "size-7 text-[12px]", add: "size-7 [&_svg]:size-3.5" },
l: { avatar: "m" as const, overlap: "-ml-2 group-hover/avatars:-ml-1", more: "size-8 text-[13px]", add: "size-8 [&_svg]:size-4" },
};
// On hover the group loosens so each face shows, and the one under the pointer lifts a little.
const spread = "[transition:margin_var(--duration-snappy)_var(--ease-snappy),translate_var(--duration-snappy)_var(--ease-snappy)] hover:z-10 hover:-translate-y-0.5";
// Up to max overlapping people, then a +N count. For owners, viewers or assignees, not a list to act on.
export function AvatarGroup({ people, max = 4, size = "m", onAdd, addLabel = "Add person", className, ...rest }: AvatarGroupProps) {
const g = groupSizes[size];
const shown = people.slice(0, max);
const more = people.length - shown.length;
const faces = (
<>
{shown.map((p, i) => (
<Avatar
key={p.name + i}
name={p.name}
src={p.src}
size={g.avatar}
className={cx("rounded-full ring-2 ring-surface-card", spread, i > 0 && g.overlap)}
/>
))}
{more > 0 ? (
<span
className={cx(
"inline-flex shrink-0 items-center justify-center rounded-full bg-surface-muted font-medium text-text-muted ring-2 ring-surface-card",
spread,
g.overlap,
g.more,
)}
aria-label={`${more} more`}
>
+{more}
</span>
) : null}
</>
);
if (!onAdd) {
return (
<div {...rest} className={cx("group/avatars flex items-center", className)}>
{faces}
</div>
);
}
// With onAdd, the add button sits just after the faces and doesn't join the overlap.
return (
<div {...rest} className={cx("flex items-center gap-1.5", className)}>
<div className="group/avatars flex items-center">{faces}</div>
<button type="button" aria-label={addLabel} onClick={onAdd} className={cx(addClasses, g.add)}>
<PlusGlyph />
</button>
</div>
);
}
Installation
With the @ochre registry set up, one command adds the component and what it imports (utils). Or copy the code above into components/ochre/avatar.tsx.
npx shadcn@latest add @ochre/avatarExamples
Initials, image, icon, square and status
import { User } from "lucide-react";
import { Avatar } from "@/components/ochre/avatar";
export default function AvatarTypes() {
return (
<div className="flex flex-wrap items-center gap-6">
<Avatar name="Maya Shah" size="l" />
<Avatar name="Ochre" size="l" shape="square" src="/icon.svg" />
<Avatar name="Guest" size="l" icon={<User />} />
<Avatar name="Northwind" size="l" shape="square" />
<Avatar name="Jonah Lee" size="l" status="online" />
<Avatar name="Ana Ruiz" size="l" status="away" />
<Avatar name="Northwind" size="l" shape="square" status="busy" />
</div>
);
}
Mark and verified
A workspace mark or a verified tick in the corner, at M, L and XL.
import { Avatar } from "@/components/ochre/avatar";
// Avatar with mark and Verified avatar, at the three sizes the Figma file draws them: M, L and XL.
export default function AvatarMarks() {
return (
<div className="grid gap-5">
<div className="flex flex-wrap items-end gap-6">
<Avatar name="Jonah Lee" size="m" mark="N" />
<Avatar name="Jonah Lee" size="l" mark="N" />
<Avatar name="Jonah Lee" size="xl" mark="N" />
<span className="text-[13px] leading-[18px] text-text-muted">Jonah, from the Northwind workspace</span>
</div>
<div className="flex flex-wrap items-end gap-6">
<Avatar name="Maya Shah" size="m" verified />
<Avatar name="Maya Shah" size="l" verified />
<Avatar name="Northwind" size="xl" shape="square" verified />
<span className="text-[13px] leading-[18px] text-text-muted">Confirmed people and organisations</span>
</div>
</div>
);
}
Avatar group
Overlapping people with a +N count at three sizes.
import { AvatarGroup } from "@/components/ochre/avatar";
const team = [
{ name: "Maya Shah" },
{ name: "Jonah Lee" },
{ name: "Ana Ruiz" },
{ name: "Tom Okafor" },
{ name: "Priti Nair" },
{ name: "Sam Ellis" },
{ name: "Leo Brandt" },
];
export default function AvatarGroupExample() {
return (
<div className="grid gap-4">
<AvatarGroup people={team} size="s" />
<AvatarGroup people={team} size="m" />
<div className="flex items-center gap-3">
<AvatarGroup people={team.slice(0, 3)} size="l" />
<span className="text-[14px] leading-5 text-text-muted">Maya, Jonah and Ana are editing</span>
</div>
</div>
);
}
Add avatar
Ends a group with a button that adds someone; on its own at S, M and L.
"use client";
import { useState } from "react";
import { AddAvatar, AvatarGroup } from "@/components/ochre/avatar";
const invitees = ["Priti Nair", "Sam Okafor", "Leo Brandt", "Ana Ruiz", "Tom Ellis"];
export default function AvatarAdd() {
const [people, setPeople] = useState([{ name: "Maya Shah" }, { name: "Jonah Lee" }]);
const add = () => setPeople((p) => (p.length - 2 < invitees.length ? [...p, { name: invitees[p.length - 2] }] : p));
return (
<div className="grid gap-5">
<div className="flex items-center gap-3">
<AvatarGroup people={people} size="m" onAdd={add} addLabel="Add to Q3 roadmap" />
<span className="font-mono text-[11px] uppercase leading-4 tracking-[0.06em] text-text-subtle">
{people.length} members
</span>
</div>
<div className="flex items-center gap-3">
<AddAvatar size="s" aria-label="Add assignee" />
<AddAvatar size="m" aria-label="Add assignee" />
<AddAvatar size="l" aria-label="Add assignee" />
</div>
</div>
);
}
Motion
Built on Ochre's ease-out curves. With reduced motion switched on, everything still works, it just doesn't move.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | – | Used for the initials and the accessible name. |
| src | string | – | Photo URL. Initials stay if it fails to load. |
| size | "xs" | "s" | "m" | "l" | "xl" | "2xl" | "m" | 24, 28, 32, 40, 48 or 64 pixels. |
| shape | "circle" | "square" | "circle" | Square for workspaces and apps. |
| status | "online" | "away" | "busy" | "offline" | – | Presence dot in the bottom corner. |
| icon | ReactNode | – | A glyph instead of initials, on the placeholder fill. |
| mark | ReactNode | – | A letter or logo in an ink square at the corner: the workspace or app. |
| verified | boolean | false | A verified tick in the corner, and ", verified" in the accessible name. |
| people (AvatarGroup) | { name: string; src?: string }[] | – | Everyone in the group, in order. |
| max (AvatarGroup) | number | 4 | How many to show before the +N count. |
| size (AvatarGroup) | "s" | "m" | "l" | "m" | 24, 28 or 32 pixels. |
| onAdd (AvatarGroup) | () => void | – | Shows an add button after the group; addLabel names it. |
| size (AddAvatar) | "s" | "m" | "l" | "m" | 24, 32 or 40 pixels. Give it an aria-label such as Add assignee. |
Usage
Use it for
- Owners, assignees and authors beside their work.
- Workspace and app switchers, as squares.
- Avatar group for who's on a project or viewing a document.
- A mark for the workspace a person belongs to or the app that acted for them; the tick for confirmed people and organisations.
- Add avatar at the end of a group or member list, when people can be added right there.
Avoid
- Avatar groups as a list people need to act on: use a list with names.
- Status dots where presence doesn't matter. They draw the eye.
- Coloured initials backgrounds per person: Ochre keeps them grey and calm.
- A mark, a tick and a status dot together. The corner holds one: mark first, then the tick, then status.