Dialog

A modal overlay that interrupts the flow to confirm an action or collect a small amount of input. Built on base-ui Dialog — focus trapping, scroll locking, Escape-to-close, and ARIA wiring come for free.

Compose the parts: Dialog (root, owns the open state), DialogTrigger (the element that opens it), and DialogContent (the popup — it renders the backdrop, the centered panel, and a corner close button). Inside the content, lay out DialogHeader (DialogTitle + DialogDescription) and DialogFooter (the actions). DialogClose dismisses the dialog from anywhere inside it. For destructive confirmations, reach for AlertDialog instead — it forces an explicit choice and traps Escape.

Basic

A trigger plus a content panel with a title, description, and a footer. Following the VESYL dialog convention, the cancel action sits on the left and the primary (here destructive) action on the right. Wrap each part’s underlying element with render so a Button becomes the trigger and the close actions.

import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@vesyl/ui-next";

export default function DialogBasic() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Cancel shipment</DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Cancel shipment</DialogTitle>
          <DialogDescription>
            The label for order #VE-10428 will be voided and the carrier pickup cancelled. This
            can't be undone.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose render={<Button variant="ghost" />}>Keep shipment</DialogClose>
          <DialogClose render={<Button variant="destructive" />}>Cancel shipment</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

With a form

Dialogs are a natural home for short forms. Put the fields between the header and footer; the panel grows to fit, and DialogContent uses spacing="default" (gap-6) so sections stay evenly spaced. Use spacing="compact" (gap-4) for dense list or picker dialogs instead of overriding the panel’s gap with className.

import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Input,
  Label,
} from "@vesyl/ui-next";

export default function DialogForm() {
  return (
    <Dialog>
      <DialogTrigger render={<Button />}>Add box</DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Add box</DialogTitle>
          <DialogDescription>
            Define a custom box to offer when packing orders at this warehouse.
          </DialogDescription>
        </DialogHeader>
        <form className="grid gap-4" onSubmit={(e) => e.preventDefault()}>
          <div className="grid gap-2">
            <Label htmlFor="box-name">Name</Label>
            <Input id="box-name" placeholder="Medium mailer" />
          </div>
          <div className="grid grid-cols-3 gap-2">
            <div className="grid gap-2">
              <Label htmlFor="box-length">Length (in)</Label>
              <Input id="box-length" type="number" placeholder="12" />
            </div>
            <div className="grid gap-2">
              <Label htmlFor="box-width">Width (in)</Label>
              <Input id="box-width" type="number" placeholder="9" />
            </div>
            <div className="grid gap-2">
              <Label htmlFor="box-height">Height (in)</Label>
              <Input id="box-height" type="number" placeholder="3" />
            </div>
          </div>
          <DialogFooter>
            <DialogClose render={<Button variant="ghost" />}>Cancel</DialogClose>
            <DialogClose render={<Button type="submit" />}>Save box</DialogClose>
          </DialogFooter>
        </form>
      </DialogContent>
    </Dialog>
  );
}

Wider content

DialogContent caps at sm:max-w-md by default. Override the width with a className (e.g. sm:max-w-2xl) when the body is a list, table, or multi-column layout that needs the room.

import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@vesyl/ui-next";

export default function DialogWide() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Review manifest</DialogTrigger>
      <DialogContent className="sm:max-w-2xl">
        <DialogHeader>
          <DialogTitle>End-of-day manifest</DialogTitle>
          <DialogDescription>
            42 shipments will be handed off to USPS on the 4:30 PM pickup.
          </DialogDescription>
        </DialogHeader>
        <div className="divide-border rounded-2xl border text-sm">
          {[
            { tracking: "9400 1000 0000 0000 1234", order: "#VE-10421", service: "Ground Advantage" },
            { tracking: "9400 1000 0000 0000 5678", order: "#VE-10422", service: "Priority Mail" },
            { tracking: "9400 1000 0000 0000 9012", order: "#VE-10423", service: "Ground Advantage" },
          ].map((row) => (
            <div key={row.tracking} className="flex items-center justify-between gap-4 px-4 py-3 not-first:border-t">
              <span className="text-foreground font-medium">{row.order}</span>
              <span className="text-muted-foreground">{row.service}</span>
              <span className="text-muted-foreground font-mono text-xs">{row.tracking}</span>
            </div>
          ))}
        </div>
        <DialogFooter>
          <Button variant="ghost">Print manifest</Button>
          <DialogClose render={<Button />}>Close manifest</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Tall content — DialogBody

A dialog taller than the viewport scrolls as one piece by default, taking its title and buttons with it. scrollable + DialogBody bounds the popup and gives the body its own scroll region, so the header and footer stay put.

import {
  Button,
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from '@vesyl/ui-next'
import { useState } from 'react'

export default function DialogScrollable() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open tall dialog
      </Button>

      <Dialog open={open} onOpenChange={setOpen}>
        <DialogContent scrollable className="max-h-[24rem]">
          <DialogHeader>
            <DialogTitle>Ship-to address</DialogTitle>
          </DialogHeader>

          <DialogBody>
            <div className="space-y-3">
              {Array.from({ length: 12 }, (_, i) => (
                <div key={i} className="space-y-1">
                  <div className="text-muted-foreground text-xs">Field {i + 1}</div>
                  <div className="bg-muted h-9 rounded-md" />
                </div>
              ))}
            </div>
          </DialogBody>

          <DialogFooter>
            <DialogClose render={<Button variant="ghost" />}>Cancel</DialogClose>
            <Button>Save</Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </>
  )
}

DialogBody bleeds to the popup’s edges and re-applies the horizontal padding inside the scroll region. That is what keeps the scrollbar in the padding gutter rather than across the right edge of a field — padding outside with the scrollbar inside is the arrangement that overlaps content.

It scrolls natively rather than wrapping ScrollArea. The platform scrollbar is thin and hides itself; a custom one is always visible and heavier than a form body needs. scrollbar-gutter: stable keeps the platforms that reserve scrollbar space from shifting content when it appears.

Edge hints are on by default here, since a bounded body gives no other sign it is cut off — but they suppress themselves when the platform draws a permanent scrollbar, which already carries that signal. Pass scrollHint={false} to drop them entirely.

Both parts are needed: scrollable alone leaves the body with no height to be constrained by, and DialogBody alone has nothing bounding it.

scrollable is opt-in because it swaps the popup to overflow-hidden, handing the scroll to the body. A dialog that is only a header and a footer — most confirms — has no body to take it, and a long description there would clip instead of scroll. So it stays opt-in until the unconditional shape keeps a fallback overflow. Reach for DialogBody in anything new either way; a hand-rolled scrolling div is what puts a scrollbar across a field’s right edge.

A wrapping <form> needs nothing. Form.Root renders no element, so the form is the only box standing between the panel and its parts — and it is a submission boundary, not layout. scrollable gives it display: contents, handing the header, body and footer straight to the panel’s column as if the form were not there. No min-h-0 flex-1 at the call site, and no spacing classes on the form.

Real chrome is different. A dialog that puts its body behind Tabs has boxes that genuinely lay out — the tab list is visible — so that dialog makes the tab panel the column itself (flex min-h-0 flex-1 flex-col) rather than the panel guessing at markup it cannot see.

The body spaces its own children (gap-6, matching what the panel gives the header and footer). Tighten a dense set of fields with contentClassName="gap-4" — a space-y-* there would add margins on top of the gap rather than replacing it.

Hiding the close button

Pass showCloseButton={false} to DialogContent to drop the corner ✕ — useful for flows that should only exit through a footer action. DialogFooter has a matching showCloseButton that appends a ready-made outline “Close” button so you don’t have to wire one up. This demo also uses spacing="compact" for the tighter panel rhythm.

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Button,
} from "@vesyl/ui-next";

export default function DialogOptions() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Printing labels…</DialogTrigger>
      <DialogContent spacing="compact" showCloseButton={false}>
        <DialogHeader>
          <DialogTitle>Generating labels</DialogTitle>
          <DialogDescription>
            Building 18 labels for the morning batch. The corner close button is hidden so the dialog
            stays put until the run finishes — the footer provides the only dismiss.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter showCloseButton />
      </DialogContent>
    </Dialog>
  );
}

Controlled

Dialog is uncontrolled by default — DialogTrigger and DialogClose toggle it for you. To drive it yourself (open it from a menu item, close it only after a mutation resolves), pass open and onOpenChange. The exported DialogProps type captures that pair for component props.

import { type DialogProps } from "@vesyl/ui-next";

function DeleteBoxDialog({ box, open, onOpenChange }: DialogProps & { box: Box }) {
  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent>{/* … */}</DialogContent>
    </Dialog>
  );
}

Reference

Dialog

Root container; owns the open state. Extends base-ui Dialog.Root props.

Prop	Type	Default	Description
`defaultOpen`	`boolean`	`false`	Initial open state (uncontrolled)
`open`	`boolean`	—	Open state (controlled)
`onOpenChange`	`(open: boolean) => void`	—	Fires when the open state should change
`modal`	`boolean`	`true`	Trap focus and block interaction behind it

DialogTrigger

The element that opens the dialog. Extends base-ui Dialog.Trigger props.

Prop	Type	Default	Description
`render`	`React.ReactElement`	—	Render as another element, e.g. `render={<Button />}`

DialogContent

The popup. Renders the backdrop, the centered panel, and (by default) a corner close button. Extends base-ui Dialog.Popup props.

Prop	Type	Default	Description
`showCloseButton`	`boolean`	`true`	Render the ✕ button in the top-right corner
`showBackdrop`	`boolean`	`true`	Render the dimming overlay; set `false` for dialogs nested in a Sheet
`spacing`	`"default" \| "compact"`	`"default"`	Direct-child gap (`gap-6` or `gap-4`)
`className`	`string`	—	Merged onto the panel — override the `sm:max-w-md` width cap here

DialogHeader

Stacks the title and description with a small gap. Plain div.

Prop	Type	Default	Description
`className`	`string`	—	Merged onto the `div`

DialogTitle

The accessible heading, wired to the dialog via ARIA. Extends base-ui Dialog.Title props.

Prop	Type	Default	Description
`className`	`string`	—	Merged onto the title

DialogDescription

Supporting copy under the title, wired to the dialog via ARIA. Links inside it are auto-underlined. Extends base-ui Dialog.Description props.

Prop	Type	Default	Description
`className`	`string`	—	Merged onto the description

DialogFooter

Lays out actions — stacked on mobile, right-aligned in a row on sm+. Plain div.

Prop	Type	Default	Description
`showCloseButton`	`boolean`	`false`	Append a ready-made outline “Close” button that dismisses
`className`	`string`	—	Merged onto the `div`

DialogClose

Dismisses the dialog when activated. Extends base-ui Dialog.Close props.

Prop	Type	Default	Description
`render`	`React.ReactElement`	—	Render as another element, e.g. `render={<Button />}`

DialogProps

Exported helper type for controlled-dialog component props.

Field	Type	Description
`open`	`boolean`	Controlled open state
`onOpenChange`	`(open: boolean) => void`	Called when the open state should change