Responsive Dialog

Anatomy

The parts mirror Dialog’s — all but DialogBody, which works as it is (see below). Each renders its Dialog… twin from the breakpoint up and its Drawer… twin below it, so anything you already know about those two holds — including that only the Dialog has a corner ✕.

import {
  ResponsiveDialog, ResponsiveDialogClose, ResponsiveDialogContent, ResponsiveDialogDescription,
  ResponsiveDialogFooter, ResponsiveDialogHeader, ResponsiveDialogTitle, ResponsiveDialogTrigger,
} from '@comitor/ui'

<ResponsiveDialog breakpoint={768}>             // Dialog from 768px up, a vaul Drawer below
  <ResponsiveDialogTrigger asChild>…</ResponsiveDialogTrigger>
  <ResponsiveDialogContent>                     // portal + overlay + panel — size, showCloseButton and
                                                // closeLabel reach the Dialog branch only
    <ResponsiveDialogHeader>
      <ResponsiveDialogTitle>…</ResponsiveDialogTitle>          // names the dialog in both branches
      <ResponsiveDialogDescription>…</ResponsiveDialogDescription>
    </ResponsiveDialogHeader>
    …                                           // long content? DialogBody scrolls in both branches
    <ResponsiveDialogFooter>
      <ResponsiveDialogClose asChild>…</ResponsiveDialogClose>  // the Drawer has no corner ✕ — always add one
    </ResponsiveDialogFooter>
  </ResponsiveDialogContent>
</ResponsiveDialog>

// Each part renders its Dialog… or Drawer… twin and carries data-variant="dialog" | "drawer".

An edit form

The read-out above the button uses the same media query as the component. Open the form on a wide window, then narrow the window below 768px — or open this page on a phone — and the same parts come up as a sheet with a grab handle. The open state is controlled here, and the draft lives above the dialog: resize across the breakpoint while it is open and your typing survives.

On open, focus goes to Display name with its text selected, in both branches. The footer’s two data-[variant=drawer]: classes are the only branch-specific styling on this page: the sheet already pads its sides by 16px and DrawerFooter adds 16px more, which would leave the buttons narrower than the fields, and the column is reversed so Save sits on top — the order DialogFooter uses on narrow screens. When something else needs to know the branch, the package’s own hook is internal; read the same query:

'use client'

import { useSyncExternalStore } from 'react'

// ResponsiveDialog's own hook is internal. This reads the same query (breakpoint 768 →
// max-width: 767px) the same way: useSyncExternalStore has the answer on the first client
// render, where useState + useEffect would render the wrong branch for one frame.
const QUERY = '(max-width: 767px)'

function subscribe(onChange: () => void) {
  const mql = window.matchMedia(QUERY)
  mql.addEventListener('change', onChange)
  return () => mql.removeEventListener('change', onChange)
}

export function useDrawerBranch() {
  return useSyncExternalStore(subscribe, () => window.matchMedia(QUERY).matches, () => false)
}

A short question

Uncontrolled, with two props that exist only in the Dialog branch: size="sm" narrows the panel and showCloseButton={false} drops the corner ✕, since Stay does the same job. In the Drawer branch both are simply not passed on. Focus opens on Stay because it comes first in the DOM — the safe answer is the one under the finger.

Leaving a channel can be undone, so a plain dialog is right. For something that destroys data, use Confirm Dialog on every screen size: it is an alert dialog that a stray tap on the overlay cannot dismiss, and it holds itself open while the request is in flight.

Long content, and where focus lands

There is no ResponsiveDialogBody, and none is needed: DialogBody is a plain min-h-0 flex-auto overflow-y-auto div, and both branches are height-capped flex columns — the Dialog at the viewport height minus 2rem, the Drawer at 80vh — so it scrolls between a pinned header and footer in either. This demo also moves the first focus: onOpenAutoFocus prevents the default and focuses the notes region, so the top of the notes stays in view, no phone keyboard appears, and the arrow keys scroll at once.

The same handler solves the classic phone problem with forms. By default focus goes to the first focusable element, and when that is a text field the keyboard slides up over half the sheet the moment it opens. Prevent the default and focus the panel itself — or go straight to the field the user came to change:

// A form in a sheet: focusing the first field pops the phone keyboard over half the form.
// Keep it down by focusing the panel itself — Radix gives it tabIndex={-1}, so it can take focus.
const panelRef = useRef<HTMLDivElement>(null)

<ResponsiveDialogContent
  ref={panelRef}
  onOpenAutoFocus={(event) => {
    event.preventDefault() // no first-field focus…
    panelRef.current?.focus({ preventScroll: true }) // …but focus must still go INSIDE, never stay on the trigger
  }}
>

// Or open straight into the field the user came to change — "Edit" next to the email row:
<ResponsiveDialogContent
  onOpenAutoFocus={(event) => {
    event.preventDefault()
    emailRef.current?.focus({ preventScroll: true })
  }}
>

Language

Responsive Dialog has no namespace of its own and exactly one built-in string: the screen-reader name of the Dialog branch’s corner ✕, closeLabel in the dialog namespace — “Close”, or “Đóng” from comitorMessagesVi.dialog. The closeLabel prop beats the nearest ComitorLocaleProvider, which beats English. The Drawer branch has no corner button, so it has no string at all. Switch the language, open the dialog, and read the name back from the DOM:

Everything else in the panel is yours and follows your own translations. Where the provider goes: Get started → Set the language.

Props

ResponsiveDialog takes Dialog’s root props plus breakpoint, and forwards them to whichever branch renders.

ResponsiveDialogContent — typed as DialogContent’s props; everything not listed goes to the panel in both branches.

The other parts. Each takes the props of its Dialog twin and className.

Known limitations

• Crossing the breakpoint remounts everything inside. The open state lives in the root and survives, but the panel is a new tree: uncontrolled field values, scroll position and focus start over. Turning an iPad mini (744px wide upright, 1133px on its side) is enough to cross 768. Keep form state above the dialog, as the edit form does.
• Without a Trigger, only the Dialog branch returns focus. Opened from state — a table row, a menu item — the Dialog branch hands focus back to whatever had it when it opened, as Dialog does since 3.3.0. The Drawer branch is vaul’s DrawerContent, which has no such return, so below the breakpoint closing drops focus on <body>. Keep a ResponsiveDialogTrigger, or return focus in onCloseAutoFocus — which works in both branches, as the job rows of the Mobile pattern do.
• Always a bottom sheet. direction, snapPoints, dismissible and the other vaul options are not in the props — the type is Dialog’s root. For a side sheet or snap points, compose Dialog and Drawer yourself with the query above.
• No corner ✕ in the Drawer branch. Swiping down and tapping the overlay are pointer-only and Escape needs a keyboard; a ResponsiveDialogClose in the footer is the only way out for everyone else.
• Anything you drag inside the sheet drags the sheet. vaul listens for pointer moves across the whole panel, so a downward drag on a cropper, a canvas or a sortable list also pulls the Drawer shut. Mark those elements data-vaul-no-drag — the Cropper page shows it.
• The viewport decides, not the container. A narrow side panel on a wide screen still gets the Dialog, and the server always renders the Dialog branch — the switch to a sheet on a phone happens as the page hydrates, which only shows if a dialog is already open at load.
• The branch is not exported. Only the parts know it, through data-variant; anything outside reads the media query itself.

Accessibility

• Both branches are a Radix Dialog underneath — vaul builds the Drawer on it — so both render role="dialog" labelled by the title and described by the description, and hide the rest of the page from assistive technology while open. Always include a title; without a description, pass aria-describedby={undefined} or Radix warns in development.
• On open, focus goes to the first focusable element inside (links are skipped, and a text field has its text selected); Tab and Shift Tab loop inside; Esc closes; focus returns to the trigger. Identical in both branches since 2.1.0 — as long as there is a ResponsiveDialogTrigger; opened from state, see Known limitations.
• Choose the first focus on purpose with onOpenAutoFocus — the panel, a specific field or a scroll region — but always somewhere inside. Leaving focus on the trigger behind the overlay is the bug this release fixed.
• Long content needs a keyboard way to scroll: give the scrolling region tabIndex and a name, as the release notes do. Safari does not make scroll containers focusable on its own.
• Ways out: Esc and a click on the overlay in both branches, the corner ✕ in the Dialog branch (named by closeLabel — say what it closes, it is read out of context), a swipe in the Drawer branch. The grab handle is decoration and never takes focus.
• Forms inside behave like any form. A submit button in the footer reaches the form through form="…", which also keeps implicit submission working: Enter in a field submits, in both branches.
• The trigger stays a real button: use asChild with a Button, never an onClick on a div.

Related

• Mobile — the phone layouts where the sheet branch matters, next to the bottom Sheet they use for detail.
• Dialog and Drawer — the two branches on their own, with every prop they take.
• Confirm Dialog — for destructive questions, on every screen size.
• Sheet — a panel from any edge that stays a panel, without the drag gesture.
• Cropper — the crop step that usually lives inside one of these.