Components
Avatar
A member as a circle, with their photo or initials, an optional presence mark, and a stack that shows who is in the room.
import * as Avatar from "@sideby/ui/avatar";
<Avatar.Root name="Maya Chen">
<Avatar.Fallback />
</Avatar.Root> When to use it
An avatar stands for one member wherever the room lists people: the presence strip, chat authors, the member list. It shows their photo when there is one and their initials when there is not. The circle is reserved for people, so nothing else in sideby uses this shape.
Every avatar needs a name. It becomes the avatar’s accessible name, read once for the whole circle, and it is where the initials come from.
Sizes
import * as Avatar from "@sideby/ui/avatar";
<Avatar.Root name="Maya Chen" size="xs"><Avatar.Fallback /></Avatar.Root>
<Avatar.Root name="Maya Chen" size="sm"><Avatar.Fallback /></Avatar.Root>
<Avatar.Root name="Maya Chen"><Avatar.Fallback /></Avatar.Root>
<Avatar.Root name="Maya Chen" size="lg"><Avatar.Fallback /></Avatar.Root> The sizes follow the control heights: xs is 28px, sm 36px, md (the default) 40px and lg 44px.
Image and fallback
import * as Avatar from "@sideby/ui/avatar";
<!-- Photo, shown once it loads -->
<Avatar.Root name="Maya Chen">
<Avatar.Image src="/avatars/maya.jpg" />
<Avatar.Fallback />
</Avatar.Root>
<!-- No photo: initials -->
<Avatar.Root name="Leo"><Avatar.Fallback /></Avatar.Root>
<!-- Blank name: a person icon -->
<Avatar.Root name=""><Avatar.Fallback /></Avatar.Root> The fallback shows while the photo loads and stays if it fails, so a broken link never leaves an empty circle. Initials are the first letter of up to two words (“Priya Raman” is PR, “Leo” is L). A blank name shows a person icon and is read as “Unnamed member”.
That holds when the photo changes or goes away too: the initials come back until a new photo has loaded, so a member never shows a broken image or an empty circle. Try it with the image control in the playground at the top of the page.
To follow the photo yourself, bind loadingStatus or pass onLoadingStatusChange. Both report every change: loading while a photo loads, loaded once it shows, and error when it fails or there is no photo.
Presence
Pass a member status and the avatar draws the status mark on its corner, in the same tone as the member status badge. The status words join the name, so a screen reader hears “Leo, buffering”.
import * as Avatar from "@sideby/ui/avatar";
<Avatar.Root name="Leo" status="buffering"><Avatar.Fallback /></Avatar.Root> The mark is small, so it is a glance cue only. Wherever the status matters, show the StatusBadge with its words next to the member too.
Stack
Avatar.Stack is the presence strip: who is in the room, overlapping. It shows up to max avatars (5 by default) and folds the rest into a +N circle. The group is named for the head count, “7 people in the room”, and the +N circle is read as “and 2 more”.
import * as Avatar from "@sideby/ui/avatar";
const members = [
{ id: "m-maya", name: "Maya Chen", src: "/avatars/maya.jpg", status: "in sync" },
{ id: "m-leo", name: "Leo", status: "buffering" },
// ...five more, each with the room's member id
];
<Avatar.Stack {members} max={5} /> Give every member an id, the room’s member id. Each avatar is tied to it, so when someone leaves, everyone else keeps their own photo or initials instead of inheriting a neighbour’s. Without an id the stack falls back to the name and photo, and two members who share both still each get their own circle.
import * as Avatar from "@sideby/ui/avatar";
<!-- Renders nothing at all -->
<Avatar.Stack members={[]} /> An empty members list renders nothing at all: no “0 people”, no placeholder circle. One member reads “1 person in the room”.
Accessibility
- The root is
role="img"with the name (and status) as itsaria-label. The photo has an emptyaltand the initials sit inside the image role, so the name is read once. - A status is never shown by the mark alone: it is part of the spoken name, and screens that need it visibly show the status words beside the member.
- The stack is a
groupnamed “N people in the room”; the overflow circle says “and N more”. - Display names render as text, never as markup, so a name that contains angle brackets shows exactly those characters.
Copy
Use the member’s display name as they typed it. Built-in words are plain: “N people in the room”, “1 person in the room”, “and N more”, “Unnamed member”.