Dialog

Headless dialog primitives for modal and non-modal overlays in Roblox UI.

Stable direction
@lattice-ui/dialog

Part of the stable direction toward v1.0.

What It Is For

Use Dialog for modal or non-modal overlays that own focus handoff, outside dismissal, and explicit close actions.

The package gives you the compound structure for triggers, content, overlay, and close controls while leaving rendering and layout fully headless.

Preview size

Live demo is experimental and may contain bugs.

Install

Global CLI command: lattice add dialog

Monorepo local script

Use your package manager wrapper when running the local lattice command.

pnpm lattice add dialog

npm package: @lattice-ui/dialog

Peer dependencies

  • @rbxts/react
  • @rbxts/react-roblox

Providers

  • @lattice-ui/layer:PortalProvider? (optional)

Registry notes

  • Dialog.Content can use PortalProvider for predictable layering.

Public Exports

  • Dialog
  • Dialog.Root
  • Dialog.Trigger
  • Dialog.Portal
  • Dialog.Content
  • Dialog.Overlay
  • Dialog.Close
  • DialogClose
  • DialogContent
  • DialogOverlay
  • DialogPortal
  • DialogRoot
  • DialogTrigger

State Model

  • Dialog.Root can be controlled with open or uncontrolled with defaultOpen.
  • modal defaults the interaction model for the whole dialog tree, and Dialog.Content controls focus trapping and focus restoration.
  • Portal, overlay, and outside-interaction dismissal are coordinated through shared layer state, not through userland event wiring.

Key API

Dialog.Root

Use open, defaultOpen, onOpenChange, and modal to define how the dialog participates in app state and surrounding interaction.

Dialog.Content

Use trapFocus, restoreFocus, and outside-interaction callbacks when you need to customize the default overlay behavior.

Dialog.Overlay

Mount the backdrop separately so you can own the visual treatment without re-implementing overlay semantics.

Dialog.Close

Attach close behavior to any host element without coupling it to a specific button implementation.

Composition Patterns

Settings or confirmation modal

Use Trigger, Portal, Overlay, Content, and Close as separate pieces so layout and visual hierarchy remain fully app-owned.

Managed focus return

Keep dialogs tied to a concrete trigger when possible so restoreFocus returns the user to a predictable origin after dismissal.

Cautions / Limits

  • Dialogs depend on portal-based layering for reliable overlay behavior; use PortalProvider near the app root.
  • A dialog is the right fit when content should own the interaction mode; use Popover for lighter anchored surfaces.
  • Keep overlay fade and panel reveal in motion; do not make dialog focus or dismissal logic depend on custom tweens.

Decision Guides