shadcn-impl-responsive-dialog-drawer AI 스킬 사용법

어떤 스킬인가요?

Use when building a modal surface that must look correct on both desktop and mobile in shadcn ui, when the design calls for a centered Dialog on large screens but a bottom-sheet Drawer on phones, when the user reports that the current Dialog feels cramped on a phone or that the on-screen keyboard covers the form fields, when wiring a delete-confirmation, edit-profile, filter-panel, share-sheet, or settings modal that must respect platform conventions (native swipe-down dismiss on iOS / Android), when building a responsive Combobox where the dropdown must become a full-height Drawer on mobile, when porting an existing Dialog to also work well on touch devices, or when the user asks "how do I make a responsive modal". Prevents the recurring failure modes of an ad-hoc responsive modal: rendering BOTH the Dialog and the Drawer simultaneously so two open surfaces appear at once and the ARIA tree has duplicate role=dialog nodes, calling useMediaQuery without an SSR guard so Next.js logs a hydration mismatch on every first paint, keeping two separate useState pairs for the Dialog open state and the Drawer open state so closing one does not close the other when the viewport resizes mid-session, hard-coding a 768px or 640px check inline in every component instead of extracting one named useMediaQuery hook, rendering different field sets or different content per breakpoint so the user loses input when they rotate the device, omitting DialogTitle and DialogDescription (or DrawerTitle and DrawerDescription) so the screen reader announces an unlabelled dialog, and forgetting that DrawerClose must wrap an asChild Button to actually close the Drawer. Covers the canonical Dialog-desktop / Drawer-mobile pattern from the official shadcn ui responsive example, the useMediaQuery hook with useSyncExternalStore (SSR-safe), the shared content component contract (same component for both surfaces, optional className for layout adjustments), the single-source open state pattern (one useState shared by Dialog and Drawer), the breakpoint choice rationale (md: 768px is the shadcn default), the ResponsiveModal orchestrator pattern that hides the branch from feature code, and the responsive Combobox variant (Popover-on-desktop / Drawer-on-mobile). This skill is the IMPLEMENTATION recipe that orchestrates the primitives taught in shadcn-syntax-dialog (B4) and shadcn-syntax-drawer (B5). Read those first if the Dialog or Drawer subcomponent trees are unclear. Keywords: responsive dialog, mobile drawer, desktop dialog, useMediaQuery, responsive modal, Dialog mobile, Drawer mobile, how do I make a responsive modal, breakpoint switch, vaul mobile, shadcn responsive modal, Dialog Drawer pattern, conditional render Dialog Drawer, matchMedia react, useSyncExternalStore media query, SSR safe useMediaQuery, hydration mismatch useMediaQuery, shared form Dialog Drawer, ResponsiveModal component, responsive Combobox Popover Drawer, Dialog cramped on phone, Drawer on desktop looks wrong, bottom sheet desktop, swipe down dismiss mobile, why is my modal too small on mobile, why does my modal show twice, 768px breakpoint shadcn, md breakpoint Tailwind, vaul on desktop, Drawer instead of Dialog on mobile, delete confirmation responsive, edit profile responsive modal, filter panel mobile drawer.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

npx skills add impertio-studio/shadcn-ui-claude-skill-package --skill shadcn-impl-responsive-dialog-drawer

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

`references/anti-patterns.md`

# Anti-patterns: Responsive Dialog + Drawer

Seven recurring failure modes that this skill prevents. Each entry pairs the wrong pattern with the correct pattern.

## 1. Rendering BOTH Dialog AND Drawer simultaneously

The single most common mistake: avoiding the `useMediaQuery` hook by mounting both surfaces and toggling visibility via Tailwind responsive utilities.

### Wrong

```tsx
export function EditProfile() {
  const [open, setOpen] = React.useState(false)
  return (
    <>
      <div className="hidden md:block">
        <Dialog open={open} onOpenChange={setOpen}>
          <DialogContent>
            <DialogTitle>Edit profile</DialogTitle>
            <ProfileForm />
          </DialogContent>
        </Dialog>
      </div>
      <div className="md:hidden">
        <Drawer open={open} onOpenChange={setOpen}>
          <DrawerContent>
            <DrawerTitle>Edit profile</DrawerTitle>
            <ProfileForm />
          </DrawerContent>
        </Drawer>
      </div>
    </>
  )
}
```

Why this fails:
- Both Radix Dialog (via `@radix-ui/react-dialog`) and Vaul (the Drawer engine) mount portal nodes with `role="dialog"` and `aria-modal="true"`. The accessibility tree now contains TWO concurrent modal dialogs; screen readers announce both, NVDA in particular reads the second one first.
- Both surfaces try to install a focus trap on `open=true`. Focus ping-pongs between the two trapped regions.
- `ProfileForm` is mounted TWICE. Each instance has its own internal state, so typing in the visually-hidden form silently fills a phantom copy. When the viewport resizes mid-edit, the user sees the other (empty) instance.
- The `hidden` Tailwind utility uses `display: none`, which Radix and Vaul cannot detect; they still process keyboard events globally. Pressing `Escape` closes both `open` flags but only one was visually active.

### Right

Single source, early return:

```tsx
const isDesktop = useMediaQuery("(min-width: 768px)")
if (isDesktop) {
  return <Dialog ...>...</Dialog>
}
return <Drawer ...>...</Drawer>
```

Only ONE surface mounts. The content component instantiates exactly once per resize that crosses the breakpoint.

## 2. `useMediaQuery` without an SSR guard (Next.js hydration mismatch)

A homegrown hook based on `useState` + `useEffect` "feels" simpler but breaks Next.js App Router.

### Wrong

```tsx
export function useMediaQuery(query: string) {
  const [matches, setMatches] = React.useState(
    typeof window !== "undefined" && window.matchMedia(query).matches
  )
  React.useEffect(() => {
    const mql = window.matchMedia(query)
    setMatches(mql.matches)
    const onChange = () => setMatches(mql.matches)
    mql.addEventListener("change", onChange)
    return () => mql.removeEventListener("change", onChange)
  }, [query])
  return matches
}
```

Why this fails:
- Server render: `typeof window !== "undefined"` is `false`, initial state is `false`, the server returns the Drawer branch HTML.
- Client first paint: still uses `false` because React reads the initial state. Returns Drawer.
- `useEffect` runs AFTER first paint: state flips to `true` on a desktop browser, React re-renders, the Drawer unmounts and the Dialog mounts.
- Result: visible flicker, console warning `Warning: Expected server HTML to contain a matching <button> in <body>` or similar hydration mismatches when the trigger button has different children per branch.

### Right

Use `useSyncExternalStore` with a `getServerSnapshot` that throws (see `examples.md` Example 1). The hook is then explicitly client-only; combined with `"use client"` on the consumer component, the server never tries to render either branch and the first client paint reads the real `matchMedia` value synchronously.

If the user really cannot tolerate any flash (they have a server-rendered shell), set the trigger button to be identical across both branches and place the branching INSIDE the modal content only.

## 3. Separate `useState` for Dialog and Drawer

Looks defensive but introduces a viewport-resize bug.

### Wrong

```tsx
const [dialogOpen, setDialogOpen] = React.useState(false)
const [drawerOpen, setDrawerOpen] = React.useState(false)
const isDesktop = useMediaQuery("(min-width: 768px)")

if (isDesktop) {
  return <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>...</Dialog>
}
return <Drawer open={drawerOpen} onOpenChange={setDrawerOpen}>...</Drawer>
```

Why this fails:
- The user opens the Drawer on a phone: `drawerOpen=true`, `dialogOpen=false`.
- They rotate the device to landscape OR resize the browser past 768px (DevTools, foldable phones, Samsung DeX, iPadOS Stage Manager).
- `isDesktop` flips to `true`, the if-branch returns `<Dialog open={dialogOpen=false}>`, which is closed.
- The modal silently disappears mid-edit. Form state inside the (now unmounted) Drawer is lost.

### Right

ONE state pair, shared:

```tsx
const [open, setOpen] = React.useState(false)
```

Both branches use the same `open` and `setOpen`. The modal stays open across viewport changes. Form state in the shared content component persists because the content component is the SAME component instance whether it lives inside Dialog or Drawer (assuming both branches pass the same children identity).

CAVEAT: even with one state, React unmounts/remounts the content component when the parent surface changes (Dialog -> Drawer). To preserve form state across resize, lift the form state up (to a parent `useState` or react-hook-form `useForm` instance OUTSIDE the modal), and pass `defaultValues` or controlled props down.

## 4. Hard-coded breakpoint inline instead of `useMediaQuery` hook

Every component re-implements the same breakpoint check, each slightly different.

### Wrong

```tsx
// In EditProfile.tsx
const [isDesktop, setIsDesktop] = React.useState(window.innerWidth > 768)

// In DeleteAccount.tsx
const [isDesktop, setIsDesktop] = React.useState(window.innerWidth >= 768)

// In ShareSheet.tsx
const isDesktop = typeof window !== "undefined" && window.matchMedia("(min-width: 640px)").matches
```

Why this fails:
- The first variant uses `>`, the second `>=`, so at exactly 768px viewport one component shows Dialog and the other shows Drawer. The user sees inconsistent modal styles on the same page.
- The third variant uses 640px (Tailwind `sm:` boundary) so a 700px tablet gets a Dialog from one feature and a Drawer from another.
- None of the variants react to live viewport changes. Resize the window, the modals do not switch.
- `window.innerWidth` is `undefined` during SSR, the first two variants throw "window is not defined" the moment a server render runs.

### Right

One hook, one constant, one default:

```ts
// src/lib/breakpoints.ts
export const MEDIA_DESKTOP = "(min-width: 768px)"

// In every consumer
const isDesktop = useMediaQuery(MEDIA_DESKTOP)
```

Changing the breakpoint across the app is then a one-line edit. The hook handles SSR safety and resize listeners.

## 5. Different content per breakpoint (UX inconsistency)

Tempting to "optimize for mobile" by trimming fields, but this introduces silent data loss.

### Wrong

```tsx
if (isDesktop) {
  return (
    <Dialog ...>
      <DialogContent>
        <ProfileFormFull /> {/* shows email, username, bio, avatar upload */}
      </DialogContent>
    </Dialog>
  )
}
return (
  <Drawer ...>
    <DrawerContent>
      <ProfileFormCompact /> {/* shows only email + username */}
    </DrawerContent>
  </Drawer>
)
```

Why this fails:
- A user opens the Drawer on a phone, fills email + username, taps Save. The save handler submits ONLY those two fields. The user's existing bio and avatar are now sent as `undefined` or empty strings, depending on serialization, and the backend overwrites them.
- Conversely, a user opens the Dialog on desktop, fills everything, rotates an iPad mini below 768px: the Dialog unmounts, the Drawer remounts with `ProfileFormCompact`, the previously typed bio is gone with no warning.
- Accessibility audits flag this as a content-disparity violation (WCAG 1.4.4 requires content not to be hidden by viewport).

### Right

ONE content component for BOTH branches. If the form is genuinely too long for a phone, reduce the form length for all screens or split it into a multi-step wizard. The mobile form is the desktop form; the surface changes, the content does not.

## 6. Missing `DialogTitle` / `DrawerTitle` (screen-reader violation)

Skipping the title because "the description already says what this is".

### Wrong

```tsx
<DialogContent>
  <p>Make changes to your profile here.</p>
  <ProfileForm />
</DialogContent>
```

Why this fails:
- Radix Dialog logs: `Warning: Missing 'DialogTitle' for the 'DialogContent'. Add a 'DialogTitle' to make the content accessible to screen readers.` Vaul logs an equivalent warning for Drawer.
- Screen readers announce the modal as "dialog" with no name. The user has no idea what just opened.
- Some audit tools (axe-core, Lighthouse a11y score) fail the page with `aria-dialog-name`.

### Right

ALWAYS include both Title and Description, on BOTH branches:

```tsx
<DialogHeader>
  <DialogTitle>Edit profile</DialogTitle>
  <DialogDescription>Make changes to your profile here.</DialogDescription>
</DialogHeader>
```

If the design genuinely requires a hidden title, wrap it in shadcn's `VisuallyHidden` slot rather than omitting it.

## 7. `DrawerClose` wrapping a `Button` WITHOUT `asChild`

The Drawer Cancel button does not actually close the Drawer, or it renders nested `<button>` elements.

### Wrong

```tsx
<DrawerFooter>
  <DrawerClose>
    <Button variant="outline">Cancel</Button>
  </DrawerClose>
</DrawerFooter>
```

Why this fails:
- Without `asChild`, `DrawerClose` renders ITS OWN button and places `<Button>Cancel</Button>` as a child. The resulting DOM is `<button><button>Cancel</button></button>`, which is invalid HTML. Browsers handle it inconsistently: clicking the inner button may or may not bubble to the outer one.
- React DevTools shows the duplicated focus ring; keyboard tab order hits both buttons.
- Form-wide `type="submit"` semantics get confused because nested buttons each default to `type="submit"`.

### Right

```tsx
<DrawerFooter>
  <DrawerClose asChild>
    <Button variant="outline">Cancel</Button>
  </DrawerClose>
</DrawerFooter>
```

`asChild` uses Radix's `Slot` pattern: `DrawerClose` merges its own props (the close handler, the `data-state` attribute) onto the child `Button` instead of rendering a wrapper. The result is ONE `<button>` element with the correct semantics.

The same rule applies to `DrawerTrigger`, `DialogTrigger`, `DialogClose`, `PopoverTrigger`, and any other Radix `*Trigger` / `*Close` primitive wrapping a real interactive element.

# Examples: Responsive Dialog + Drawer All examples assume TypeScript, React 18+, Next.js App Router (or any framework with `"use client"` boundaries), Tailwind CSS, and shadcn ui components already installed via `npx shadcn@latest add dialog drawer popover command button input label`. ## Example 1: SSR-safe `useMediaQuery` hook Location: `src/hooks/use-media-query.ts`. ```ts "use client" import * as React from "react" export function useMediaQuery(query: string): boolean { const subscribe = React.useCallback( (callback: () => void) => { const mediaQueryList = window.matchMedia(query) mediaQueryList.addEventListener("change", callback) return () => { mediaQueryList.removeEventListener("change", callback) } }, [query], ) const getSnapshot = () => window.matchMedia(query).matches const getServerSnapshot = () => { // useMediaQuery is a client-only hook. The "use client" directive on the // consumer plus useSyncExternalStore's server-snapshot slot keep the hook // out of the server render path. Throwing here surfaces accidental // server invocations early instead of silently returning false. throw new Error("useMediaQuery is a client-only hook") } return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot) } ``` Why `useSyncExternalStore` and not `useState` + `useEffect`: - `useState` + `useEffect` initializes with a fallback value (`false`) and updates on mount, producing a one-frame mismatch between server render and first client paint. Next.js logs `Hydration failed because the initial UI does not match what was rendered on the server`. - `useSyncExternalStore` is the React-blessed primitive for subscribing to external stores; React 18 schedules the subscription correctly across concurrent renders. ## Example 2: Shared `ProfileForm` content component ```tsx "use client" import * as React from "react" import { cn } from "@/lib/utils" import { Button } from "@/components/ui/button" import { Input } from "@/components/ui/input" import { Label } from "@/components/ui/label" type ProfileFormProps = React.ComponentProps<"form"> & { onDone?: () => void } export function ProfileForm({ className, onDone, ...rest }: ProfileFormProps) { return ( <form {...rest} className={cn("grid items-start gap-6", className)} onSubmit={(e) => { e.preventDefault() // ...persist the data... onDone?.() }} > <div className="grid gap-3"> <Label htmlFor="email">Email</Label> <Input type="email" id="email" defaultValue="shadcn@example.com" /> </div> <div className="grid gap-3"> <Label htmlFor="username">Username</Label> <Input id="username" defaultValue="@shadcn" /> </div> <Button type="submit">Save changes</Button> </form> ) } ``` The `cn("grid items-start gap-6", className)` merge is critical: the Dialog branch passes no `className`, so the form keeps its default spacing; the Drawer branch passes `className="px-4"`, which `cn` (from `tailwind-merge`) appends without conflicting with the grid. ## Example 3: `ResponsiveModal` orchestrator Location: `src/components/responsive-modal.tsx`. ```tsx "use client" import * as React from "react" import { useMediaQuery } from "@/hooks/use-media-query" import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger, } from "@/components/ui/dialog" import { Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, DrawerTrigger, } from "@/components/ui/drawer" const DEFAULT_BREAKPOINT = "(min-width: 768px)" type ResponsiveModalProps = { open: boolean onOpenChange: (open: boolean) => void title: string description?: string trigger?: React.ReactNode children: React.ReactNode breakpoint?: string } export function ResponsiveModal({ open, onOpenChange, title, description, trigger, children, breakpoint = DEFAULT_BREAKPOINT, }: ResponsiveModalProps) { const isDesktop = useMediaQuery(breakpoint) if (isDesktop) { return ( <Dialog open={open} onOpenChange={onOpenChange}> {trigger ? <DialogTrigger asChild>{trigger}</DialogTrigger> : null} <DialogContent className="sm:max-w-[425px]"> <DialogHeader> <DialogTitle>{title}</DialogTitle> {description ? ( <DialogDescription>{description}</DialogDescription> ) : null} </DialogHeader> {children} </DialogContent> </Dialog> ) } return ( <Drawer open={open} onOpenChange={onOpenChange}> {trigger ? <DrawerTrigger asChild>{trigger}</DrawerTrigger> : null} <DrawerContent> <DrawerHeader className="text-left"> <DrawerTitle>{title}</DrawerTitle> {description ? ( <DrawerDescription>{description}</DrawerDescription> ) : null} </DrawerHeader> {children} </DrawerContent> </Drawer> ) } ``` ## Example 4: Edit-profile feature using `ResponsiveModal` ```tsx "use client" import * as React from "react" import { Button } from "@/components/ui/button" import { ResponsiveModal } from "@/components/responsive-modal" import { ProfileForm } from "@/components/profile-form" export function EditProfilePanel() { const [open, setOpen] = React.useState(false) return ( <ResponsiveModal open={open} onOpenChange={setOpen} title="Edit profile" description="Make changes to your profile here. Click save when done." trigger={<Button variant="outline">Edit Profile</Button>} > <ProfileForm className="px-4 md:px-0" onDone={() => setOpen(false)} /> </ResponsiveModal> ) } ``` Note the `className="px-4 md:px-0"` pattern: `px-4` is active on the Drawer (mobile), `md:px-0` overrides it to remove padding on the Dialog (desktop) because `DialogContent` already pads. This single Tailwind expression replaces the official example's runtime branching of the `className` prop. ## Example 5: Full delete-confirmation responsive flow A destructive action benefits from the responsive pattern because the consequences of an accidental confirm are higher on a small screen. The Drawer branch shows a footer with two distinct buttons; the Dialog branch reuses the same pattern. ```tsx "use client" import * as React from "react" import { Button } from "@/components/ui/button" import { useMediaQuery } from "@/hooks/use-media-query" import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, } from "@/components/ui/dialog" import { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger, } from "@/components/ui/drawer" export function DeleteAccountButton({ onConfirm }: { onConfirm: () => Promise<void> }) { const [open, setOpen] = React.useState(false) const [busy, setBusy] = React.useState(false) const isDesktop = useMediaQuery("(min-width: 768px)") async function handleConfirm() { setBusy(true) try { await onConfirm() setOpen(false) } finally { setBusy(false) } } const Title = "Delete account" const Body = "This action cannot be undone. Your profile, posts, and saved drafts will be permanently removed." if (isDesktop) { return ( <Dialog open={open} onOpenChange={setOpen}> <DialogTrigger asChild> <Button variant="destructive">Delete account</Button> </DialogTrigger> <DialogContent className="sm:max-w-[425px]"> <DialogHeader> <DialogTitle>{Title}</DialogTitle> <DialogDescription>{Body}</DialogDescription> </DialogHeader> <DialogFooter> <Button variant="outline" onClick={() => setOpen(false)} disabled={busy}> Cancel </Button> <Button variant="destructive" onClick={handleConfirm} disabled={busy}> {busy ? "Deleting..." : "Delete account"} </Button> </DialogFooter> </DialogContent> </Dialog> ) } return ( <Drawer open={open} onOpenChange={setOpen}> <DrawerTrigger asChild> <Button variant="destructive">Delete account</Button> </DrawerTrigger> <DrawerContent> <DrawerHeader className="text-left"> <DrawerTitle>{Title}</DrawerTitle> <DrawerDescription>{Body}</DrawerDescription> </DrawerHeader> <DrawerFooter className="pt-2"> <Button variant="destructive" onClick={handleConfirm} disabled={busy}> {busy ? "Deleting..." : "Delete account"} </Button> <DrawerClose asChild> <Button variant="outline" disabled={busy}> Cancel </Button> </DrawerClose> </DrawerFooter> </DrawerContent> </Drawer> ) } ``` Notable details: - `Title` and `Body` are extracted to local constants so they cannot drift between branches. - The Drawer puts the destructive button ABOVE the cancel button (standard iOS / Android action-sheet ordering). The Dialog puts cancel on the LEFT and destructive on the RIGHT (standard desktop dialog ordering). This intentional asymmetry follows platform conventions. - `busy` state is shared across both surfaces, identical loading text. ## Example 6: Responsive Combobox (Popover-on-desktop / Drawer-on-mobile) The Combobox composition (Popover + Command) breaks on phones because the Popover anchors to the trigger and the on-screen keyboard covers it. The fix: same `Command` body, switch the wrapper from `Popover` to `Drawer`. ```tsx "use client" import * as React from "react" import { Check, ChevronsUpDown } from "lucide-react" import { cn } from "@/lib/utils" import { Button } from "@/components/ui/button" import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, } from "@/components/ui/command" import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover" import { Drawer, DrawerContent, DrawerTrigger } from "@/components/ui/drawer" import { useMediaQuery } from "@/hooks/use-media-query" type Status = { value: string; label: string } const statuses: Status[] = [ { value: "backlog", label: "Backlog" }, { value: "todo", label: "Todo" }, { value: "in progress", label: "In progress" }, { value: "done", label: "Done" }, { value: "canceled", label: "Canceled" }, ] export function StatusCombobox() { const [open, setOpen] = React.useState(false) const [selected, setSelected] = React.useState<Status | null>(null) const isDesktop = useMediaQuery("(min-width: 768px)") const Trigger = ( <Button variant="outline" className="w-[200px] justify-between"> {selected ? selected.label : "Set status"} <ChevronsUpDown className="opacity-50" /> </Button> ) const Body = ( <Command> <CommandInput placeholder="Filter status..." /> <CommandList> <CommandEmpty>No results found.</CommandEmpty> <CommandGroup> {statuses.map((s) => ( <CommandItem key={s.value} value={s.value} onSelect={(v) => { setSelected(statuses.find((x) => x.value === v) ?? null) setOpen(false) }} > <Check className={cn( "mr-2 h-4 w-4", selected?.value === s.value ? "opacity-100" : "opacity-0", )} /> {s.label} </CommandItem> ))} </CommandGroup> </CommandList> </Command> ) if (isDesktop) { return ( <Popover open={open} onOpenChange={setOpen}> <PopoverTrigger asChild>{Trigger}</PopoverTrigger> <PopoverContent className="w-[200px] p-0" align="start"> {Body} </PopoverContent> </Popover> ) } return ( <Drawer open={open} onOpenChange={setOpen}> <DrawerTrigger asChild>{Trigger}</DrawerTrigger> <DrawerContent> <div className="mt-4 border-t">{Body}</div> </DrawerContent> </Drawer> ) } ``` The key reuse trick: `Body` is a JSX expression, NOT a component. Extracting it as a constant inside the render keeps `Command`'s internal state (highlighted item, filter input value) bound to a single instance per render; if it were extracted as a separate component called twice with different parents, the two parents would each get a fresh instance. The Drawer branch wraps `Body` in `<div className="mt-4 border-t">` because the bare `Command` looks unfinished without a divider above the search input on a bottom sheet. The Popover branch does not need this because `PopoverContent`'s border provides the visual frame.

# Methods Reference: Responsive Dialog + Drawer All signatures below are TypeScript. Files are owned by the consumer project (shadcn ownership model). Names match the official shadcn ui `drawer-dialog` example unless explicitly noted. ## useMediaQuery (hook signature) Location: `src/hooks/use-media-query.ts`. ```ts function useMediaQuery(query: string): boolean ``` - Parameter `query`: a CSS media query string. The canonical value for this skill is `"(min-width: 768px)"`, matching the official shadcn ui example and Tailwind's `md:` breakpoint. - Return: `true` when the query matches the current viewport, `false` otherwise. - Implementation MUST use `React.useSyncExternalStore` (React 18+). The `useState` + `useEffect` variant is disallowed in this skill because it causes a Next.js App Router hydration mismatch on first paint. - The hook is client-only. Callers MUST place it inside a `"use client"` component. On the server, `useSyncExternalStore` falls back to `getServerSnapshot`, which throws by design. - The query string is the `useCallback` dependency. Passing a literal string is safe; passing a dynamically-built string requires `useMemo` upstream to avoid re-subscribing every render. ## ResponsiveModal (component signature) Location: `src/components/responsive-modal.tsx`. ```ts type ResponsiveModalProps = { open: boolean onOpenChange: (open: boolean) => void title: string description?: string trigger?: React.ReactNode children: React.ReactNode breakpoint?: string } export function ResponsiveModal(props: ResponsiveModalProps): JSX.Element ``` Contract: - `open` + `onOpenChange` are forwarded to BOTH `Dialog` and `Drawer`. Callers MUST own the state via `useState`. Uncontrolled mode (`defaultOpen`) is NOT exposed because controlled state is required to close the surface from inside `children` (e.g. after a successful submit). - `title` becomes `DialogTitle` on desktop and `DrawerTitle` on mobile. REQUIRED for screen-reader compliance. Empty string is allowed by Radix Dialog only if `aria-labelledby` is overridden upstream; this skill assumes the simpler labelled path and requires a non-empty title. - `description` becomes `DialogDescription` / `DrawerDescription`. Optional but RECOMMENDED (Radix Dialog warns when absent). - `trigger` is rendered inside `DialogTrigger asChild` / `DrawerTrigger asChild`. Omit it to open the modal imperatively via `onOpenChange(true)` from elsewhere. - `children` renders inside `DialogContent` (no automatic padding wrapper) and inside `DrawerContent` below `DrawerHeader` (no automatic padding wrapper). Callers MUST handle their own padding, typically with the pattern `className="px-4 md:px-0"` on the inner element, because `DialogContent` already pads horizontally but `DrawerContent` does not. - `breakpoint` defaults to `"(min-width: 768px)"`. Override only when the design system mandates a different switch point. ## Shared content component contract The component rendered inside `children` MUST satisfy three rules: 1. Accept an OPTIONAL `className` prop and merge it via `cn(...)`. The Drawer branch passes `className="px-4"` to compensate for `DrawerContent`'s missing horizontal padding; the Dialog branch passes nothing. 2. Render IDENTICAL field sets, identical labels, and identical validation messages on both branches. NEVER show fewer fields on one branch. 3. Receive callbacks (`onDone`, `onCancel`, `onSubmit`) as props so the orchestrator can close the modal via `setOpen(false)` after a successful action. The component itself MUST NOT call `setOpen` directly; it does not know which surface is active. Recommended TypeScript shape: ```ts type SharedContentProps = { className?: string onDone?: () => void } ``` The official example's `ProfileForm` uses `React.ComponentProps<"form">` so the form element passes through `id`, `name`, `onSubmit` etc. without additional plumbing. ## Open-state contract ONE `useState` pair for the surface, shared by Dialog and Drawer: ```ts const [open, setOpen] = React.useState(false) ``` ANTI-CONTRACT (do NOT do this): ```ts const [dialogOpen, setDialogOpen] = React.useState(false) const [drawerOpen, setDrawerOpen] = React.useState(false) ``` The two-state variant breaks when the viewport crosses the breakpoint while the modal is open (rotate device, drag window): the now-active branch reads `false` because only the other branch's flag was updated, so the user's open modal silently disappears. ## Breakpoint constant (recommended) When `ResponsiveModal` is used in more than three places, extract the breakpoint to a single constant so a design-system change requires one edit: ```ts // src/lib/breakpoints.ts export const MEDIA_DESKTOP = "(min-width: 768px)" ``` The orchestrator then reads `useMediaQuery(MEDIA_DESKTOP)` and accepts an override via the `breakpoint` prop for the rare exception. ## DrawerClose vs DialogClose Both close the modal when clicked. Both REQUIRE the `asChild` pattern when wrapping a `Button`: ```tsx <DrawerClose asChild> <Button variant="outline">Cancel</Button> </DrawerClose> ``` Without `asChild`, the close primitive renders its own button and nests it inside the consumer's button, producing invalid HTML (`<button>` inside `<button>`). `DialogContent` ALSO ships a built-in top-right close affordance, controlled by the `showCloseButton` prop (defaults to `true`). `DrawerContent` does NOT. This is why the canonical pattern adds a `DrawerFooter` with a `DrawerClose` Cancel button on the mobile branch but not on the desktop branch. ## Responsive Combobox variant signature The same pattern applies to the Combobox composition (Popover + Command). The desktop branch renders `<Popover>`; the mobile branch renders `<Drawer>` with the same `<Command>` body inside. ```ts function ResponsiveCombobox<TOption>(props: { value: TOption | null onValueChange: (next: TOption | null) => void options: TOption[] getLabel: (opt: TOption) => string placeholder?: string }): JSX.Element ``` The implementation lives in `examples.md`. The decision to switch to a Drawer on mobile is driven by the same UX rule: a Popover anchored to a trigger button is unusable on a phone because the on-screen keyboard covers it and the list cannot scroll into view.

`SKILL.md`

---
name: shadcn-impl-responsive-dialog-drawer
description: >
  Use when building a modal surface that must look correct on both desktop and
  mobile in shadcn ui, when the design calls for a centered Dialog on large
  screens but a bottom-sheet Drawer on phones, when the user reports that the
  current Dialog feels cramped on a phone or that the on-screen keyboard
  covers the form fields, when wiring a delete-confirmation, edit-profile,
  filter-panel, share-sheet, or settings modal that must respect platform
  conventions (native swipe-down dismiss on iOS / Android), when building a
  responsive Combobox where the dropdown must become a full-height Drawer on
  mobile, when porting an existing Dialog to also work well on touch devices,
  or when the user asks "how do I make a responsive modal".
  Prevents the recurring failure modes of an ad-hoc responsive modal: rendering
  BOTH the Dialog and the Drawer simultaneously so two open surfaces appear at
  once and the ARIA tree has duplicate role=dialog nodes, calling
  useMediaQuery without an SSR guard so Next.js logs a hydration mismatch on
  every first paint, keeping two separate useState pairs for the Dialog open
  state and the Drawer open state so closing one does not close the other when
  the viewport resizes mid-session, hard-coding a 768px or 640px check inline
  in every component instead of extracting one named useMediaQuery hook,
  rendering different field sets or different content per breakpoint so the
  user loses input when they rotate the device, omitting DialogTitle and
  DialogDescription (or DrawerTitle and DrawerDescription) so the screen
  reader announces an unlabelled dialog, and forgetting that DrawerClose
  must wrap an asChild Button to actually close the Drawer.
  Covers the canonical Dialog-desktop / Drawer-mobile pattern from the
  official shadcn ui responsive example, the useMediaQuery hook with
  useSyncExternalStore (SSR-safe), the shared content component contract
  (same component for both surfaces, optional className for layout
  adjustments), the single-source open state pattern (one useState shared by
  Dialog and Drawer), the breakpoint choice rationale (md: 768px is the
  shadcn default), the ResponsiveModal orchestrator pattern that hides the
  branch from feature code, and the responsive Combobox variant
  (Popover-on-desktop / Drawer-on-mobile).
  This skill is the IMPLEMENTATION recipe that orchestrates the primitives
  taught in shadcn-syntax-dialog (B4) and shadcn-syntax-drawer (B5). Read
  those first if the Dialog or Drawer subcomponent trees are unclear.
  Keywords: responsive dialog, mobile drawer, desktop dialog, useMediaQuery,
  responsive modal, Dialog mobile, Drawer mobile, how do I make a responsive
  modal, breakpoint switch, vaul mobile, shadcn responsive modal,
  Dialog Drawer pattern, conditional render Dialog Drawer, matchMedia react,
  useSyncExternalStore media query, SSR safe useMediaQuery,
  hydration mismatch useMediaQuery, shared form Dialog Drawer,
  ResponsiveModal component, responsive Combobox Popover Drawer,
  Dialog cramped on phone, Drawer on desktop looks wrong,
  bottom sheet desktop, swipe down dismiss mobile,
  why is my modal too small on mobile, why does my modal show twice,
  768px breakpoint shadcn, md breakpoint Tailwind, vaul on desktop,
  Drawer instead of Dialog on mobile, delete confirmation responsive,
  edit profile responsive modal, filter panel mobile drawer.
license: MIT
compatibility: "Designed for Claude Code. Requires shadcn ui evergreen-2026."
metadata:
  author: OpenAEC-Foundation
  version: "1.0"
---

# shadcn ui: responsive Dialog (desktop) + Drawer (mobile)

This skill is the IMPLEMENTATION recipe for the most-requested compositional pattern in shadcn ui: a single modal surface that renders as a centered `Dialog` on desktop and as a bottom-sheet `Drawer` on mobile. The pattern comes directly from the official `drawer-dialog` example in the shadcn ui repository.

ALWAYS read `shadcn-syntax-dialog` first if the Dialog subcomponent tree (`DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`) is unclear.

ALWAYS read `shadcn-syntax-drawer` first if the Drawer subcomponent tree, the `direction` prop, or the Vaul-specific semantics (snap points, dismissible, repositionInputs) are unclear.

## Quick Reference

### The pattern in five lines

```tsx
"use client"
const [open, setOpen] = React.useState(false)
const isDesktop = useMediaQuery("(min-width: 768px)")
if (isDesktop) return <Dialog open={open} onOpenChange={setOpen}>...<Content />...</Dialog>
return <Drawer open={open} onOpenChange={setOpen}>...<Content />...</Drawer>
```

Five non-negotiable invariants:
1. ONE `useState` pair for the open flag. Dialog and Drawer share it.
2. ONE `useMediaQuery` hook to pick the surface. NEVER hard-code the breakpoint inline.
3. ONE shared content component (`<ProfileForm />`, `<DeleteForm />`, etc). Same props on both branches.
4. NEVER render both Dialog and Drawer at the same time. Use `if (isDesktop) return ...` (early return), NOT both branches mounted.
5. ALWAYS include `DialogTitle` + `DialogDescription` on the desktop branch and `DrawerTitle` + `DrawerDescription` on the mobile branch. Both Radix Dialog and Vaul require a labelled title for screen readers.

### Files you generate

```
src/
├── hooks/
│   └── use-media-query.ts          # the SSR-safe useMediaQuery hook
└── components/
    ├── ui/
    │   ├── dialog.tsx              # shadcn add dialog
    │   └── drawer.tsx              # shadcn add drawer
    └── responsive-modal.tsx        # the orchestrator (optional but recommended)
```

## Decision Tree: Dialog only, Drawer only, or responsive?

```
Is the modal ALWAYS modal (blocking, must-acknowledge)?
├─ YES, AND target is form-factor-agnostic (edit profile, delete confirm, filters)
│   └─ USE responsive Dialog + Drawer (this skill)
├─ YES, AND target is desktop-only admin UI
│   └─ USE Dialog only (see shadcn-syntax-dialog)
└─ NO, it is a mobile-first action sheet (share, sort, add-to-cart)
    └─ USE Drawer only on all viewports (see shadcn-syntax-drawer)
```

When in doubt: responsive. The official example uses it for an "Edit Profile" form, which is the canonical case.

## Step 1: Install the useMediaQuery hook

shadcn ui itself does NOT ship a `useMediaQuery` hook in `components/ui/`. You write it once into `src/hooks/use-media-query.ts`. The official shadcn ui example imports from `@/hooks/use-media-query`, which means the project owner authored it.

ALWAYS use the `useSyncExternalStore` variant (React 18+). NEVER use a `useState` + `useEffect` variant in a Next.js App Router project, because the initial render runs server-side, where `window` does not exist, and a `useEffect` variant produces a hydration mismatch on the very first paint.

Full implementation in `references/examples.md`. Signature:

```ts
function useMediaQuery(query: string): boolean
```

Returns `true` when the query matches, `false` otherwise. On the server, `useSyncExternalStore` falls back to the `getServerSnapshot` slot, which in this hook throws. shadcn ui's official example calls the hook from inside a `"use client"` component, so the server never executes it.

Breakpoint choice: `(min-width: 768px)` matches Tailwind's `md:` breakpoint. This is what the official shadcn `drawer-dialog` example uses and what this skill standardizes on. If a project uses a different design system breakpoint, pass it as an argument to a `ResponsiveModal` prop. NEVER copy the literal `768px` across many components.

## Step 2: Write the shared content component

The single most important design rule of the pattern: ONE content component renders inside BOTH surfaces. NEVER duplicate the form, body, or action layout per branch. NEVER show fewer fields on mobile and more on desktop, because a viewport rotation mid-edit then silently drops the hidden state.

The shared component MUST accept `className` (because Drawer often needs `px-4` padding that Dialog already supplies via `DialogContent`'s default padding) and MAY accept callbacks like `onSubmit` that close the modal.

```tsx
function ProfileForm({ className, onDone }: {
  className?: string
  onDone?: () => void
}) {
  return (
    <form className={cn("grid items-start gap-6", className)} onSubmit={...}>
      ...inputs...
      <Button type="submit">Save changes</Button>
    </form>
  )
}
```

Full example with all imports in `references/examples.md`.

## Step 3: Wire the conditional render

The canonical shape from the official shadcn ui example, with the responsive branching kept inside ONE component:

```tsx
"use client"

import * as React from "react"
import { useMediaQuery } from "@/hooks/use-media-query"
import { Button } from "@/components/ui/button"
import {
  Dialog, DialogContent, DialogDescription, DialogHeader,
  DialogTitle, DialogTrigger,
} from "@/components/ui/dialog"
import {
  Drawer, DrawerClose, DrawerContent, DrawerDescription,
  DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger,
} from "@/components/ui/drawer"

export function EditProfileModal() {
  const [open, setOpen] = React.useState(false)
  const isDesktop = useMediaQuery("(min-width: 768px)")

  if (isDesktop) {
    return (
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogTrigger asChild>
          <Button variant="outline">Edit Profile</Button>
        </DialogTrigger>
        <DialogContent className="sm:max-w-[425px]">
          <DialogHeader>
            <DialogTitle>Edit profile</DialogTitle>
            <DialogDescription>
              Make changes to your profile here. Click save when done.
            </DialogDescription>
          </DialogHeader>
          <ProfileForm onDone={() => setOpen(false)} />
        </DialogContent>
      </Dialog>
    )
  }

  return (
    <Drawer open={open} onOpenChange={setOpen}>
      <DrawerTrigger asChild>
        <Button variant="outline">Edit Profile</Button>
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader className="text-left">
          <DrawerTitle>Edit profile</DrawerTitle>
          <DrawerDescription>
            Make changes to your profile here. Click save when done.
          </DrawerDescription>
        </DrawerHeader>
        <ProfileForm className="px-4" onDone={() => setOpen(false)} />
        <DrawerFooter className="pt-2">
          <DrawerClose asChild>
            <Button variant="outline">Cancel</Button>
          </DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  )
}
```

Note four details from the official example:
- `DialogContent` carries `className="sm:max-w-[425px]"` so it does not stretch to the full Dialog max-width.
- `DrawerHeader` carries `className="text-left"` because the default `DrawerHeader` is centered (mobile bottom sheet convention) but a form header reads better left-aligned.
- `ProfileForm` carries `className="px-4"` only inside the Drawer, because `DialogContent` already pads its content while `DrawerContent` does not pad horizontally.
- `DrawerFooter` contains a `DrawerClose asChild` Cancel button. The Dialog branch does not include a Cancel button because Dialog ships a built-in close affordance (top-right X) via `DialogContent`'s `showCloseButton` default. The Drawer does not.

## Step 4: Extract the orchestrator (`ResponsiveModal`)

After two or three usages of the pattern, the if-else branching duplicates. Extract a `ResponsiveModal` orchestrator that hides the branch from feature code. ALWAYS forward `open`, `onOpenChange`, `title`, `description`, and `children` so the orchestrator stays content-agnostic.

```tsx
// components/responsive-modal.tsx
"use client"

import * as React from "react"
import { useMediaQuery } from "@/hooks/use-media-query"
import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"
import { Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, DrawerTrigger } from "@/components/ui/drawer"

type ResponsiveModalProps = {
  open: boolean
  onOpenChange: (open: boolean) => void
  title: string
  description?: string
  trigger?: React.ReactNode
  children: React.ReactNode
  breakpoint?: string
}

export function ResponsiveModal({
  open, onOpenChange, title, description, trigger, children,
  breakpoint = "(min-width: 768px)",
}: ResponsiveModalProps) {
  const isDesktop = useMediaQuery(breakpoint)
  if (isDesktop) {
    return (
      <Dialog open={open} onOpenChange={onOpenChange}>
        {trigger ? <DialogTrigger asChild>{trigger}</DialogTrigger> : null}
        <DialogContent className="sm:max-w-[425px]">
          <DialogHeader>
            <DialogTitle>{title}</DialogTitle>
            {description ? <DialogDescription>{description}</DialogDescription> : null}
          </DialogHeader>
          {children}
        </DialogContent>
      </Dialog>
    )
  }
  return (
    <Drawer open={open} onOpenChange={onOpenChange}>
      {trigger ? <DrawerTrigger asChild>{trigger}</DrawerTrigger> : null}
      <DrawerContent>
        <DrawerHeader className="text-left">
          <DrawerTitle>{title}</DrawerTitle>
          {description ? <DrawerDescription>{description}</DrawerDescription> : null}
        </DrawerHeader>
        {children}
      </DrawerContent>
    </Drawer>
  )
}
```

Feature code then reads cleanly:

```tsx
<ResponsiveModal
  open={open}
  onOpenChange={setOpen}
  title="Edit profile"
  description="Make changes to your profile here."
  trigger={<Button variant="outline">Edit Profile</Button>}
>
  <ProfileForm className="md:px-0 px-4" onDone={() => setOpen(false)} />
</ResponsiveModal>
```

The orchestrator deliberately does NOT include a `DrawerFooter` + `DrawerClose` block, because the Drawer footer is content-specific (Cancel vs. Confirm vs. Apply). Place footer buttons inside `children`. See `references/examples.md` for a `DeleteConfirmation` variant that adds an explicit destructive-action footer.

## Step 5: Breakpoint choice rationale

`(min-width: 768px)` maps to Tailwind's `md:` and matches the official shadcn `drawer-dialog` example. The rationale:
- iPhone 14 Pro Max landscape is 932px wide so it lands on the Dialog branch in landscape; the Drawer is reserved for portrait phones, which is where the bottom-sheet ergonomics matter (thumb reach).
- iPad Mini portrait is 768px so it lands on the boundary; the example uses `min-width: 768px`, which includes 768px exactly, so iPad Mini portrait gets the Dialog.
- Smaller tablets (768px landscape but narrower in portrait) follow the same logic.

If the design system uses a different breakpoint (some teams prefer 640px to match Tailwind `sm:`, others 1024px to match `lg:` because they consider iPad-sized devices "mobile"), pass it via the `ResponsiveModal` `breakpoint` prop. NEVER fork the hook per call site.

## Anti-patterns

NEVER render both `<Dialog>` and `<Drawer>` and toggle them via CSS (`hidden md:block` + `block md:hidden`). Both Radix Dialog and Vaul mount portal nodes with `role="dialog"` and `aria-modal="true"`; rendering both creates a duplicated ARIA tree, focus-trap collisions, and `Title must be inside Dialog.Root` warnings from Radix when Vaul portals into a Dialog-managed focus zone. Use the early-return pattern instead.

Full list of seven failure modes with concrete examples in `references/anti-patterns.md`.

## Reference Files

- `references/methods.md`: `useMediaQuery` signature, `ResponsiveModal` props contract, shared-content-component contract.
- `references/examples.md`: SSR-safe `useMediaQuery` source, shared `FormContent`, `ResponsiveModal` orchestrator, full delete-confirmation flow, responsive Combobox (Popover-on-desktop / Drawer-on-mobile).
- `references/anti-patterns.md`: seven recurring failure modes with the wrong-then-right code for each.

## Companion Skills

- `shadcn-syntax-dialog` (Batch B4): Dialog subcomponent tree, `showCloseButton`, `DialogTitle` / `DialogDescription` a11y requirements, controlled `open` / `onOpenChange`.
- `shadcn-syntax-drawer` (Batch B5): Drawer subcomponent tree, Vaul-specific props (`direction`, `snapPoints`, `fadeFromIndex`, `dismissible`, `modal`, `repositionInputs`), bottom-sheet conventions.
- `shadcn-impl-form-validation`: when the responsive modal hosts a form (90% of cases), the form-state, submit, and `setError` patterns live here.
- `shadcn-impl-rsc-vs-client-boundaries`: the responsive modal MUST live in a `"use client"` boundary because `useMediaQuery` reads `window.matchMedia`. The orchestrator file itself carries `"use client"`; pages importing it stay server components.

## Sources

- Official responsive Dialog/Drawer example: `apps/v4/registry/new-york-v4/examples/drawer-dialog.tsx` in `shadcn-ui/ui` (verified 2026-05-19).
- shadcn ui Drawer docs: https://ui.shadcn.com/docs/components/radix/drawer (verified 2026-05-19).
- shadcn ui Dialog docs: https://ui.shadcn.com/docs/components/radix/dialog (verified 2026-05-19).
- `useMediaQuery` with `useSyncExternalStore`: https://github.com/uidotdev/usehooks (verified 2026-05-19).
- Vaul Drawer primitive: https://github.com/emilkowalski/vaul.