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 lays its children out as a gap-6 grid so sections stay evenly spaced.

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>
  );
}

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.

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 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
`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