interlace

Dialog

A MODAL dialog: it traps focus, dismisses on Escape and on an outside click, marks the rest of the page inert while open, and restores focus to the trigger on close. Base UI owns all of that, which is exactly why this file never says so anywhere else — and…

overlayclient≥ 320pxuiv1.4.0

Preview

Dialog — live renderprimitives-dialog--default ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL
npx shadcn@latest add https://ds.interlace.tools/r/dialog.json
With the @interlace alias
npx shadcn@latest add @interlace/dialog

Behavior

What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.

Keyboard path

apps/storybook/src/stories/primitives/Dialog.stories.tsx ↗

5 steps, 1 key press — replayed on every PR by the play function of OpenCloseFlow. Axe cannot press a key, so this — not the a11y scan — is what proves the component is operable without a mouse.

  1. 1Open dialog by clicking trigger
  2. 2Dialog has accessible name + description
  3. 3Focus moves INTO the dialog (trap entered)
  4. 4Escape closes dialogEscape
  5. 5Focus is RESTORED to the trigger

Escape is locked, not merely exercised. This primitive is in KEYBOARD_DRIVEN + MUST_ASSERT_ESCAPE — deleting the dismissal assertion from the story fails overlay-nav-keyboard-lock, so the path above cannot quietly stop being tested.

Measured contrast

packages/ui/__tests__/theme-contract-lock.test.ts ↗

Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is muted-foreground on background at 7.82:1 (harbor · light), against a floor of 4.5:1.

Measured WCAG contrast ratios per token pair and theme
PairinterlacelightinterlacedarkharborlightharbordarkFloor
muted-foreground on backgroundsecondary copy9.41:111.32:17.82:19.52:14.5:1SC 1.4.3
muted-foreground on cardsecondary copy in a card9.41:110.48:18.25:18.64:14.5:1SC 1.4.3
ring on backgroundfocus ring (SC 2.4.13)8.80:111.79:18.39:110.03:13.0:1SC 1.4.11
ring on cardfocus ring inside a card8.80:110.92:18.86:19.10:13.0:1SC 1.4.11

Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.

Text equivalent

packages/ui/src/primitives/dialog.tsx ↗

A chart's alt text is not a sentence about the chart — the equivalent of the data is the data. This is what a screen reader gets, read out of the source the install writes into your tree.

Label, not a data equivalentShips sr-only copy

Ships sr-only copy for what the visual carries by position, colour or icon alone — a label, not a full data equivalent.

Runtime contract

packages/ui/vitest.config.ts ↗

Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.

Render boundary
'use client'

Hydrates. It brings JavaScript to any route that imports it — put the boundary here, not at the page.

Minimum viewport
MIN_VIEWPORT = 320

Declared, not assumed. Below 320 CSS px the preflight contract draws a dev-mode outline — how to switch it on.

Coverage gate
not in the gate

The 100% gate currently covers src/charts/**/*.{ts,tsx} and src/lib/**/*.{ts,tsx} and src/primitives/{button-variants,data-state-model,meter-scale,skeleton-variants}.ts and src/primitives/{alert,aspect-ratio,avatar,badge,box,breadcrumb,button,callout,card,checkbox,code-editor,container,data-state,focus-ring,grade-badge,grid,input,label,meter,pagination,published-date,reading-time,section,section-boundary,separator,skip-link,stack,stat-strip,tag,textarea,typography,visually-hidden}.tsx and src/patterns/lint-playground.tsx. This file is outside it — the glob widens in phase 7.2.

History

This component is at v1.4.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

@interlace/ui 1.1.01 entry

  • Changedpatch

    Six defects found by upgrading a real consumer, plus five found by reading the components closely enough to document them. **Meteors' glow never painted.** It read var(--color-meteor-glow) while its cssVars declare --meteor-glow; --color-* is the Tailwind @theme namespace and only cssVars.theme populates it, so the whole box-shadow was invalid at computed-value time. **This was broken only for registry consumers** — our own docs site hand-declares the --color- form. **ArticleCard cropped 28% off every cover.** h-44 is 176px; at a ~302px tile that is a 1.72:1 box against a 2.381:1 image. Now aspect-[1000/420] — the ratio the card already declared on its <img>. It also gains a renderImage slot, because every Next.js consumer was re-patching the same line to use next/image and the design system cannot depend on it. **BorderBeam and StarsBackground had no aria-hidden at all** — six purely decorative nodes a screen reader walked. **CloudParticles defaulted bodyColor to currentColor**, painting volumetric clouds in the inherited text colour. **NumberTicker gains notation**, because six-figure metrics overflow a tile at 320px. Also: SheetCompose and DialogCompose each mounted a second backdrop, so a composed dialog dimmed the page twice as much as the hand-composed tree the docs show; Accordion dropped className on the animated Panel; Tooltip accepted delay and discarded it; PopoverAnchor was a second trigger. **useReducedMotion was one frame late.** The canonical useState(false) plus effect returns false on the first render, so every gated component painted one frame of exactly the motion the user turned off. useSyncExternalStore reads during render and closes that on client renders; on hydration the server cannot know the preference, which is what the stylesheet reset is for. Badge drops 'use client' — verified with a real server-component build.

    Components

@interlace/ui 1.0.01 entry

Import

12 named exports — pull the parts you need.

Public API
import { Dialog, DialogClose, DialogCompose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, MIN_VIEWPORT } from '@/components/ui/dialog';

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

DialogComposeProps

PropTypeDescription
trigger*React.ReactNodeElement that opens the dialog. Typically a Button.
openbooleanOpen state — controlled. Omit for uncontrolled.
onOpenChange(open: boolean) => voidChange handler for `open`.
title*React.ReactNodeDialog title — required for ARIA labelling.
descriptionReact.ReactNodeOptional one-line description under the title.
childrenReact.ReactNodeOptional content under the description.
footerReact.ReactNodeOptional footer row — typically Cancel + Confirm buttons.
classNamestringOverride the Content className (size, padding).

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour
Owned by @base-ui/react/dialog — focus trapping, dismissal and typeahead come from the headless primitive, not from us.
Focus ring (WCAG 2.2 SC 2.4.13)
Inherited from the preflight focus contract shipped in @interlace/theme.
Reduced motion
No animation to gate.
ARIA in the source
None — semantics come from the element or the Base UI primitive rather than hand-written ARIA.

Examples

3 more states from the same story file.

composeprimitives-dialog--compose ↗
open close flowprimitives-dialog--open-close-flow ↗
reduced motionprimitives-dialog--reduced-motion ↗

R-rule compliance

Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.

RuleConceptWhere
R4Extends native el + JSDoc`React.ComponentProps<typeof BaseDialog.*>` on every export
R5data-testid type-requiredInherited via consumer-supplied `data-testid` on `...props`
R6data-slot on every named part`data-slot="dialog"` / `"dialog-trigger"` / `"dialog-portal"` / `"dialog-close"` / `"dialog-overlay"` / `"dialog-popup"`
R7className merged + ...rest + ref`cn(...)` merged className; `{...props}` spread to root
R8No `isXxx` prefix on booleansAll boolean props inherited from Base UI use the no-`is` form
R11Composition over prop-drillingDialogContent / DialogHeader / DialogFooter / DialogTitle / DialogDescription compound parts
R12Reuse primitives — don't wrapXIcon from lucide-react is slotted, not wrapped in a `DialogCloseIcon`
R13Build with the ecosystem`@base-ui/react/dialog` provides keyboard / focus / portal / ARIA
R14Controlled + uncontrolledInherited from `BaseDialog.Root` — `open` + `onOpenChange` + `defaultOpen`
R16No internal couplingDialogClose accepts children; consumer slots their own button if needed
R17API parity with MUI/shadcnShape mirrors shadcn/ui Dialog + Base UI primitives — no deviation
R18Tailwind only — no inline styleEvery visual class is Tailwind; zero `style={{}}` in this file
R19Tokens only — no raw hex/rgbaVisual classes use theme tokens (`bg-background`, `text-foreground`, `border`)
R20AA contrastTokens guarantee contrast in light + dark via the theme
R23CLS=0Overlay is positioned via `fixed inset-0`; no layout shift
R24Product-neutral vocabularyAll names structural (`Dialog`, `Title`, `Description`, `Footer`) — no domain terms
R26A11y from headless primitiveAll ARIA / keyboard / focus handled by `@base-ui/react/dialog`

Minimum viewport

This primitive declares MIN_VIEWPORT = 320 CSS px (DESIGN_PRINCIPLES #14). When mounted in a container narrower than this, the preflight contract draws a dev-mode outline so the regression is visible during local development.

Opt-in to the dev-mode warning
<body data-interlace-dev>...</body>

Add the data-interlace-dev attribute to the body in development builds only — preflight then outlines any primitive whose container is below its declared data-min-viewport.

Dependencies

Base UI primitive
@base-ui/react/dialog
Lucide icons
  • XIcon
NPM dependencies
  • @base-ui/react
  • lucide-react
Registry dependencies

Source

The full implementation — components/ui/dialog.tsx once installed.

288 lines · TypeScript
github ↗
'use client';

import * as React from 'react';

// @interlace/dialog v1.4.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/dialog
// What changed since: https://ds.interlace.tools/c/dialog#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — Dialog (gold-standard reference for the interlace-component skill)
 *
 * A MODAL dialog: it traps focus, dismisses on Escape and on an outside click,
 * marks the rest of the page inert while open, and restores focus to the
 * trigger on close. Base UI owns all of that, which is exactly why this file
 * never says so anywhere else — and why a reader searching for "modal I can
 * close with escape" could not find it. Behaviour a consumer relies on has to
 * be written down in the file they install, not left implicit in a dependency.
 *
 * This file is the canonical example of the portable component-modeling floor.

…268 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/dialog.json