Modal

Base UI Dialog (focus trap, Esc, scroll-lock, a11y) skinned as an Echo device panel. Enter uses motion.summon; exit is a GSAP tween that completes before unmount via useGsapPresence + actionsRef. sound.transition on open.

Feel A device panel that swells out of a small pill in the middle of the room, like an island opening, and gathers back into it when dismissed.

every state →

Or let the agent fetch it: get_component("modal") on the Echo MCP server.

Installation

npx echo-ui-cli add modal

First time? Run npx echo-ui-cli init once — it sets the project up, and add refuses to run before it.

At a glance

Version: 0.3.0
Weight: 771 B · 54.0 KB with what it imports · 953 B of CSS (minified and gzipped; React not counted)
Needs: gsap, @base-ui/react
Keyboard: Escape or a click on the backdrop closes it.
Reduced motion: The panel fades in and out without blooming from its pill; the backdrop fades faster.
Sound: transition when it opens.

Usage

tsx

import { HardwareButton } from "@/echo/hardware-button";
import { Modal } from "@/echo/modal";

<Modal
  trigger={<HardwareButton>Settings</HardwareButton>}
  title="Settings"
  description="Tune the device."
>
  <p>Body content…</p>
</Modal>

Composition

Modal

Examples

Basic modal

A trigger plus title/description/body.

tsx

<Modal
  trigger={<HardwareButton>Settings</HardwareButton>}
  title="Settings"
  description="Tune the device."
>
  <p>Body content…</p>
</Modal>

With footer actions

Footer for confirm/cancel.

tsx

<Modal trigger="Delete" title="Are you sure?" footer={<HardwareButton variant="primary">Confirm</HardwareButton>} />

Accessibility

Base UI Dialog: role="dialog" and aria-modal, named by title and described by description.
Focus moves into the panel, stays there while it is open, and returns to the trigger when it closes. The page behind cannot scroll.
Escape or a click on the backdrop closes it.

Tested against WCAG 2.2 AA on every release:

axe — No axe violations, in the component's own gallery and on its page.
keyboard — Every action is reachable and operable from the keyboard alone.
focus-visible — Focus is visible on every focusable part, in normal and forced-colors mode.
forced-colors — State stays visible when the look's colours are replaced by the system's.
target-size — Every target's real hit area is at least 24×24px, at every density.
reflow — Content reflows into 320px and survives a doubled text size.

Not covered: screen-reader: not yet verified by a person. Everything above is a machine check; a person has not yet driven this component with a screen reader.

Motion & sound

Motion tokens: island, summon, follow
Reduced motion: The panel fades in and out without blooming from its pill; the backdrop fades faster.
Sound: transition when it opens.

Props

Modal props
Prop	Type	Default
`trigger`What opens the modal. An element (e.g. a HardwareButton) becomes the trigger itself; text is wrapped in a plain trigger.	`ReactNode`
`title`The dialog title — also its accessible name. Always pass one.	`ReactNode`
`description`One line under the title, announced with it.	`ReactNode`
`footer`Actions row under the body, e.g. confirm and cancel buttons.	`ReactNode`
`size`The panel's width: sm 22rem, md (the default) 30rem, lg 42rem, each held inside a narrow screen.	`"sm" \| "md" \| "lg"`	`"md"`
`showClose`Show the × in the corner. Default true; turn it off only when the dialog's own actions close it.	`boolean`	`true`
`defaultOpen`	`boolean`	`false`
`container`Where the popup mounts; defaults to <body>. Pass an element inside a scoped theme so the popup wears that theme, not the :root one.	`unknown`

Anti-patterns

Do not add a CSS transition to the popup — GSAP owns its transform/opacity; a CSS transition will fight it.
Do not skip actionsRef when animating exit with JS — Base UI can't detect GSAP and will unmount too early.
The package is @base-ui/react, not @base-ui-components/react (agents have stale training data).

Changelog

v0.3.0 · 2026-10-12 · ChangedEvery item needs echo-ui-core 0.3.0 (all components). The drawn device, readability past AA and the design tests live in core, and the components that use them are built against it, so each item now declares echo-ui-core >=0.3.0 <0.4.0. Update core with the items: npm install echo-ui-core@^0.3.0 (or your package manager's), then npx echo-ui-cli update. An item whose files didn't change is the same code under a new version; the 0.2.0 files stay published.
v0.2.0 · 2026-10-04 · AddedThe light device (echo-ui-core, echo-ui-cli). Echo can be light: a pale chassis makes a device molded in light plastic, like a white calculator or a cream radio, and a dark one makes the device Echo has always been. There's no setting and no mode to switch; the chassis decides (devicePolarity, and values.polarity on the theme). On a light device the page is light: its ground, the well, is the body barely set in. Caps get their own ladder, a step lighter than the body with a lit rim that stops short of white, so they keep their bevel; undersides and seams are shaded darker; dim text moves toward the ground by the same step as on a dark device, and reads about 6:1 on it. Screens are paper glass printed in ink, because a glow on a pale body is a smudge. What's lit (an LED, the current rail) is still the accent, held to 3:1 on every ground, so on is brighter than off; the text it prints (a readout, a count, a current tab) and the focus ring are the accent's ink, a step deeper and held to AA, in the new accent-ink role. The primary cap is the same cap as a dark device's, the accent with a light label: its label is the new primary-cap-ink role, and progress cells, loader dots and a meter's fill, the same plastic, read 3:1 on the page. A neutral cap or a slider that fills with it under its own dark label fills with the new pour-* roles, the accent's pale stops. Shadows are drawn at half their weight, in a deep colour of the body's own hue (--echo-cast-ink) instead of black. Every guarantee holds as it does on a dark device, and the contrast sweep now runs on light bodies too. A dark seed makes exactly the theme it did before, and the new roles equal the ones they stand for there. The components that mixed a recess toward black, painted paper in the text colour or lit a pillow of light with it read the theme's new --echo-shade-ink, --echo-paper-stock and --echo-paper-ink instead, with the old value as the fallback, and a reflective screen reads --echo-screen-*; the components that print a lit label read --echo-primary-cap-ink and --echo-accent-ink the same way; every rail is drawn in the glow, and every focus ring, the ring recipes included, in the ink. style use wears a light style now, and style check says which device a style makes. A dark screen tint on a light body is still refused: one text colour can't serve both, and the theme says so.
v0.2.0 · 2026-10-04 · ChangedComments only, no behaviour change. Comments in the component source used to cite documents, milestones and ticket numbers from Echo's own planning, none of which exist in your project. The citations are gone and the sentences around them stay. Where a comment was only a citation, it now says what it meant. Three development warnings (HardwareButton's engraved/caption checks and StatusDot's missing-label check) also dropped the ticket code at the end of the message. echo-ui diff will show changes in most items; none of them are to code.
v0.2.0 · 2026-10-04 · ChangedAn item's version is now a function of declared data, not of how the changelog is formatted. The version an item ships under is published once and never rewritten, and it used to be inferred from prose: a regex for a bolded "Breaking" run across the whole unreleased section, and attribution by "does a bullet mention this name in backticks". One breaking entry therefore moved every item that changed that cycle, and an entry explaining that "Menu and Sheet are unchanged here" filed itself as a change to Menu and Sheet — which it really had.
v0.2.0 · 2026-10-04 · ChangedBreaking: Echo's public API names Echo's own types, not Base UI's. Eleven items put a @base-ui/react type straight into a signature you write against — BaseSwitch.Root.ChangeEventDetails on a change handler, ComponentProps<typeof BaseSelect.Portal>["container"] on a portal target. That made Echo's API a downstream of Base UI's internals: an upstream rename would have been a breaking Echo release triggered by somebody else's refactor.
v0.2.0 · 2026-10-04 · ChangedThe agent brief says Echo has not shipped. llms.txt and the MCP server's instructions led with npx echo-ui-cli init, and that name on npm is a reserved stub with no executable — so a model following the brief wrote an install step that fails with npx's own error. The brief now opens with the caveat, and the docs carry it on every surface that shows a command. One switch (CLI_RELEASED) silences all of them at launch, and a test refuses to let one move without the others. Affects all components only in what the brief says about installing them; no item's props, CSS or rendered semantics change.
v0.2.0 · 2026-10-04 · ChangedEcho's home is echo-ui.com. The registry, the docs and the packages all move to it from echo.nawwara.studio. Nothing was published under the old host, so no echo.json anywhere points at it and there is nothing to migrate — this is the last release where that is true.
v0.2.0 · 2026-10-04 · ChangedWeights, line heights, letter-spacing, z-index, border widths and icon sizes come from the theme scales in all components, with the old value as a fallback, so components keep working with echo-ui-core@0.0.1. Strays moved to the nearest step: most by under a pixel; HardwareButton icons are 14/16/20px (were 15/17/19).
v0.2.0 · 2026-10-04 · FixedA light device's recesses keep the body's hue in Chromium (echo-ui-core, BUG-166). Chromium drops the hue of a colour under 0.02 chroma when it mixes in oklch, and draws the mix at hue 0, a rose. A light device's plastic is that grey, so on a lilac body every field, track and rail was pink. A mix made only of greys is made in oklab now, which has no hue to lose; a mix with an accent in it stays in oklch. On a dark device nothing you can see changes.
v0.2.0 · 2026-10-04 · FixedOn a phone, a tapped part no longer stays lit (BUG-143). A phone leaves what you tapped under :hover until the next tap, so a table row stayed shaded and a trigger stayed lit after the finger lifted. Hover styles now apply only where there's a pointer that can hover (@media (hover: hover)), in all 23 components that had one. Checked, active and focus styles that shared a rule with them still apply everywhere.
v0.2.0 · 2026-10-04 · FixedProps the docs did not list. HardwareButton (icon, trailingIcon, target, rel), Modal (trigger, title, description, footer), Popover (trigger, title), Tooltip (trigger), Slider (value, onValueChange, aria-label, aria-labelledby), NumberField (onValueChange), SoundProvider (backend) and Textured (dither, noise) now appear in the prop tables, llms-full.txt and the MCP server.
v0.2.0 · 2026-10-04 · FixedPopups opened inside a dialog appeared behind it. A Select, Popover, Tooltip or Menu inside a Modal or Sheet opened under the dialog's backdrop. They now stack above it.
v0.2.0 · 2026-10-04 · FixedA trigger element from a server component was wrapped in a second button on a Next.js dev server, for Modal, AlertDialog, Popover and Tooltip. It now becomes the trigger itself.
v0.2.0 · 2026-10-04 · FixedContent now reflows into a 320px screen (400% zoom) and survives a doubled browser text size (WCAG 1.4.10, 1.4.4), across all components. Select's 180px floor, NumberField's readout, Segmented and Steps as flex items, EmptyState's grid columns, and Avatar's fixed-pixel disc all gave way; Panel counts its padding inside a width you set (box-sizing: border-box), so a <Panel style={{ width: 220 }}> is now 220px wide overall rather than 260px.

Preview