Components
Dialog
A modal layer for content that needs the room's full attention for a moment, with focus held inside until it closes.
import * as Dialog from "@sideby/ui/dialog";
import { buttonVariants } from "@sideby/ui/button";
<Dialog.Root>
<Dialog.Trigger class={buttonVariants({ variant: "outline" })}>Room details</Dialog.Trigger>
<Dialog.Content>
<Dialog.Header>
<Dialog.Title>Room details</Dialog.Title>
<Dialog.Description>Share the code with a friend so they land in the same room.</Dialog.Description>
</Dialog.Header>
<dl class="grid grid-cols-[auto_1fr] items-baseline gap-x-4 gap-y-2">
<dt class="font-mono text-label uppercase text-muted-foreground">Room code</dt>
<dd class="font-mono tabular-nums">fra1-k7m2q9</dd>
<dt class="font-mono text-label uppercase text-muted-foreground">Watching</dt>
<dd>4 people</dd>
</dl>
<Dialog.Footer>
<Dialog.Close class={buttonVariants({ variant: "outline" })}>Close</Dialog.Close>
<Dialog.Close class={buttonVariants()}>Copy link</Dialog.Close>
</Dialog.Footer>
</Dialog.Content>
</Dialog.Root> When to use it
Use a Dialog when a short task or a bit of detail needs the room’s full attention: room details, a share sheet, the house rules. Everything behind it stops responding until it closes, so keep it short and give it one clear way out.
For a yes-or-no question about something that cannot be undone, use an alert dialog instead. It cannot be dismissed by clicking outside, and it asks for an explicit answer.
Long content
The dialog caps its height at the dynamic viewport height minus twice its top offset. Longer content scrolls inside the dialog, and the page behind it stays put.
import { buttonVariants } from "@sideby/ui/button";
import * as Dialog from "@sideby/ui/dialog";
<Dialog.Root>
<Dialog.Trigger class={buttonVariants({ variant: "outline" })}>Read the rules</Dialog.Trigger>
<Dialog.Content>
<Dialog.Header>
<Dialog.Title>House rules</Dialog.Title>
<Dialog.Description>Six things to know before the lights go down.</Dialog.Description>
</Dialog.Header>
<ol class="grid gap-4">
{#each rules as [heading, body]}
<li class="grid gap-1">
<span class="font-semibold">{heading}</span>
<span class="text-body text-muted-foreground">{body}</span>
</li>
{/each}
</ol>
<Dialog.Footer>
<Dialog.Close class={buttonVariants()}>Got it</Dialog.Close>
</Dialog.Footer>
</Dialog.Content>
</Dialog.Root> In both themes
The scrim uses the overlay-scrim token: the foreground at 38% in the light theme and the background at 72% in the dark theme. To show a dialog in a theme island, portal it into the island with portalProps.
import { buttonVariants } from "@sideby/ui/button";
import * as Dialog from "@sideby/ui/dialog";
<!-- Portal the dialog into the island, so the scrim and the surface take the island's theme. -->
<div id="room-light" class="light">
<Dialog.Root>
<Dialog.Trigger class={buttonVariants({ variant: "outline" })}>Open in light</Dialog.Trigger>
<Dialog.Content portalProps={{ to: "#room-light" }}>
<Dialog.Header>
<Dialog.Title>Room details</Dialog.Title>
<Dialog.Description>The same dialog in the light theme.</Dialog.Description>
</Dialog.Header>
<Dialog.Footer>
<Dialog.Close class={buttonVariants()}>Done</Dialog.Close>
</Dialog.Footer>
</Dialog.Content>
</Dialog.Root>
</div> Parts
Dialog.Rootholds the open state (bind:open).Dialog.Triggeropens it; style it withbuttonVariants.Dialog.Contentportals the scrim and the surface to the end of the page. It shows a close button in the top-right corner unlessshowClose={false}.Dialog.HeaderstacksDialog.TitleandDialog.Description.Dialog.Footerholds the actions.Dialog.Closecloses the dialog from anywhere inside it.
Keyboard
- Enter or Space on the trigger opens the dialog and moves focus inside it.
- Tab and Shift+Tab cycle through the dialog’s controls only. Focus never leaves while it is open.
- Escape closes it, and so does the close button.
- When it closes, focus goes back to the trigger.
Accessibility
- Bits UI owns the behaviour: the
dialogrole,aria-modal, the focus trap, Escape, focus return and the scroll lock. Do not rebuild them. - The title names the dialog. Every dialog needs a
Dialog.Title; the description is tied to it as well, so a screen reader reads both on open. - The close button is an icon button labelled Close.
- The page behind is inert while the dialog is open, so a pointer or a screen reader cannot reach it.
On phones
- The dialog sits 12vh from the top (
dialog-offset-top) and fills the width minus a margin, up to 40rem. - Its height is capped in
dvh, so the browser’s own toolbars never push the actions off screen. - Below
smthe footer stacks in reverse: the primary action, written last, lands on top, nearest the thumb. Fromsmthe actions sit in a row on the right.
Copy
- The title says what the dialog is for: “Room details”, “House rules”. Sentence case, no full stop.
- Actions are verbs: “Copy link”, “Got it”, “Close”. Write the primary action last.
- Keep it short. If a dialog needs a scrollbar on a laptop, it might want to be a page.