Data Display
Avatar
Avatar — image, initials, or icon, in that order of preference.
import { Avatar } from 'omaris' Examples
Fallbacks
Image, then initials, then an icon — in that order of preference, so a missing photo degrades instead of leaving a hole.
<script lang="ts"> import { Avatar } from 'omaris';</script><Avatar name="Omer Chetin" /><Avatar name="Amina Yusuf" colorize /><Avatar initials="RH" colorize /><Avatar> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"> <circle cx="12" cy="8" r="3.5" /> <path d="M4.5 20a7.5 7.5 0 0 1 15 0" stroke-linecap="round" /> </svg></Avatar>Sizes shapes status
xs and sm for a table cell or a chip, lg and xl for a profile header; square for an organisation, a status dot for presence.
<script lang="ts"> import { Avatar } from 'omaris';</script><Avatar size="xs" name="Hevi Salih" colorize /><Avatar size="sm" name="Hevi Salih" colorize /><Avatar size="md" name="Hevi Salih" colorize /><Avatar size="lg" name="Hevi Salih" colorize /><Avatar size="xl" name="Hevi Salih" colorize /><Avatar shape="square" name="Karwan Ali" colorize /><Avatar name="Dilan Karim" colorize status="online" /><Avatar name="Rania Hadi" colorize status="busy" />Group
Give the group the same size as the avatars, or the overlap will not match.
<script lang="ts"> import { Avatar, AvatarGroup } from 'omaris';</script><AvatarGroup overflow={12}> <Avatar name="Amina Yusuf" colorize /> <Avatar name="Dilan Karim" colorize /> <Avatar name="Hevi Salih" colorize /> <Avatar name="Karwan Ali" colorize /></AvatarGroup><AvatarGroup size="sm"> <Avatar size="sm" name="Amina Yusuf" colorize /> <Avatar size="sm" name="Dilan Karim" colorize /> <Avatar size="sm" name="Hevi Salih" colorize /></AvatarGroup>When to use it
Use it for
- A person in a table row, a comment, an assignee on a card.
srcwhen there is a photo,namefor initials when there is not, an icon inchildrenwhen there is neither. The initials show until the image has decoded. - A team, an organisation, a product.
shape="square"is the rounded square for things that are not people. - Presence.
status="online",away,busyorofflineputs a dot on the edge of the shape, at every size, without clipping it. - The people on a thread or a project, stacked.
AvatarGroupwithoverflowfor the trailing "+n".
Not for
- A picture that is content, not identity, like a product photo → an
<img>, or Image Viewer when it opens full screen. - A count or a status word beside a name → Badge. The presence dot is the only state an avatar carries.
- Choosing a person from a list → Combobox with an Avatar in each row and the picked one as a Chip.
- A decorative icon in a tinted circle on an empty screen → Empty, which draws that circle itself.
Do
- Pass
nameeven whensrcis set. It shows while the photo loads and stays if the URL 404s, so a broken image never leaves a hole. - Turn on
colorizeeverywhere or nowhere. The hue comes from the name, so the same person is the same colour on every screen only if every avatar opts in. - Give
AvatarGroupthe samesizeas the avatars inside it. The overlap is per size and a mismatch shows at once. - Use
xsandsmin a table cell or a chip,mdin a list row,lgandxlin a profile header.
Don't
- Add
overflow-hiddenon the root to round a photo. Themediaslot already clips, and the presence dot sits outside the root. - Write
initialsby hand unless the derived pair is wrong, like a mononym or a company name. "Ada L." already becomes "AL". - Stack more than about five in a group. That is what
overflowis for.
Quick reference
size Avatarsmmd(default)lgxl
shape Avatarcircle(default)square
status Avatarnone(default)onlineawaybusyoffline
size AvatarGroupxssmmd(default)lgxl
API
Avatar
Avatar — image, initials, or icon, in that order of preference.
The image is only shown once it has actually decoded, so a broken or slow URL falls back to the initials instead of flashing a blank hole. Initials get a deterministic tint derived from the name, so the same person is the same color everywhere in the app.
import { Avatar } from 'omaris' Parts
Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.
root- Sizing, shape and the fallback colours live here — and nothing clips. The presence dot is a child of this box and is meant to sit proud of a circle's edge;
overflow-hiddenhere is what used to shave a slice off it. media- The clipping layer. Only the picture and the initials are cut to the shape, so the dot outside it survives.
image- No description in the source yet.
status- The ring that marks a live/away state, MD3 presence style.
Props
size Defaults to 'md'
AvatarSize smmdlgxl
shape Defaults to 'circle'
AvatarShape circlesquare- MD3's rounded square, for org and product avatars.
status Defaults to 'none'
AvatarStatus Presence dot in the bottom corner.
noneonlineawaybusyoffline
src string alt string name string Full name. Initials and the fallback tint are derived from it.
initials string Override the derived initials.
colorize Defaults to false
boolean Paint the initials fallback with the name-derived tint.
class string classes AvatarClasses Per-part Tailwind overrides. class still covers the root.
children Snippet Shown when there's no image and no name — an icon, usually.
AvatarGroup
A stack of overlapping avatars — the people on a thread, the members of a team.
Give it the same size as the avatars inside it, or the overlap will not match. overflow adds the trailing "+n" for the ones that did not fit.
import { AvatarGroup } from 'omaris' Props
size Defaults to 'md'
AvatarSize Overlap amount. Must match the avatars' own size to look right.
xssmmdlgxl
overflow number Renders a "+n" chip after the children.
class string classes ClassesOf<typeof avatarGroupVariants> Tailwind per part.
children Snippet