Components
Dialog
Modal dialogs for focused tasks, forms, and detail views.
Dialog is a modal surface for content that temporarily takes over the page context. Use it for
editing, creating, viewing details, authentication, and complex forms.
The component is built on Base UI Dialog and exported from @orkest/ui/client. Base UI owns focus
trapping, scroll locking, dismissal, and portal behavior; Orkest UI owns the visual design and public
API.
Basic usage#
import { Button, Stack } from '@orkest/ui';
import {
Dialog,
DialogBody,
DialogClose,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogOverlay,
DialogPortal,
DialogTitle,
DialogTrigger,
Field,
FieldLabel,
Input,
} from '@orkest/ui/client';
export function Example() {
return (
<Dialog>
<DialogTrigger>Edit profile</DialogTrigger>
<DialogPortal>
<DialogOverlay />
<DialogContent>
<DialogHeader>
<DialogTitle>Edit profile</DialogTitle>
<DialogDescription>
Update the name and email shown on your account.
</DialogDescription>
</DialogHeader>
<DialogBody>
<Stack gap={4}>
<Field>
<FieldLabel>Display name</FieldLabel>
<Input defaultValue="Ada Lovelace" />
</Field>
<Field>
<FieldLabel>Email</FieldLabel>
<Input type="email" defaultValue="ada@example.com" />
</Field>
</Stack>
</DialogBody>
<DialogFooter>
<DialogClose>Cancel</DialogClose>
<DialogClose render={<Button>Save changes</Button>} />
</DialogFooter>
</DialogContent>
</DialogPortal>
</Dialog>
);
}Anatomy#
Dialogowns the open state and modal behavior.DialogTriggeropens the dialog. It renders a primary Button by default.DialogPortalmoves the dialog to the document body.DialogOverlayrenders the backdrop.DialogContentcenters the dialog, limits its height, and can render the built-in close action.DialogHeadergroupsDialogTitleandDialogDescription.DialogBodyscrolls when the content exceeds the available height.DialogFooteraligns the actions.DialogClosecloses the dialog and renders a secondary Button by default.
Compose DialogTrigger and DialogClose with render when you need a different Button variant or a
custom element.
Controlled state#
import { useState } from 'react';
import { Button, Stack, Text } from '@orkest/ui';
import {
Dialog,
DialogClose,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogOverlay,
DialogPortal,
DialogTitle,
} from '@orkest/ui/client';
export function Example() {
const [open, setOpen] = useState(false);
return (
<Stack direction="row" gap={3} wrap align="center">
<Button onClick={() => setOpen(true)}>Open settings</Button>
<Text size="sm" tone="muted">
{open ? 'Status: open' : 'Status: closed'}
</Text>
<Dialog open={open} onOpenChange={setOpen}>
<DialogPortal>
<DialogOverlay />
<DialogContent>
<DialogHeader>
<DialogTitle>Workspace settings</DialogTitle>
<DialogDescription>
The dialog state is owned by the parent component.
</DialogDescription>
</DialogHeader>
<DialogFooter>
<DialogClose>Done</DialogClose>
</DialogFooter>
</DialogContent>
</DialogPortal>
</Dialog>
</Stack>
);
}Sizes#
DialogContent supports sm, md, lg, xl, and full. The viewport keeps a safe gutter and the
surface shrinks to the available width on small screens.
import { Box, Stack } from '@orkest/ui';
import {
Dialog,
DialogClose,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogOverlay,
DialogPortal,
DialogTitle,
DialogTrigger,
} from '@orkest/ui/client';
const sizes = ['sm', 'md', 'lg', 'xl', 'full'] as const;
export function Example() {
return (
<Box width="100%" maxWidth="30rem">
<Stack direction="row" gap={2} wrap>
{sizes.map((size) => (
<Dialog key={size}>
<DialogTrigger variant="outline">{size}</DialogTrigger>
<DialogPortal>
<DialogOverlay />
<DialogContent size={size}>
<DialogHeader>
<DialogTitle>{size} dialog</DialogTitle>
<DialogDescription>
Resize the viewport to see the responsive constraints.
</DialogDescription>
</DialogHeader>
<DialogFooter>
<DialogClose>Close</DialogClose>
</DialogFooter>
</DialogContent>
</DialogPortal>
</Dialog>
))}
</Stack>
</Box>
);
}Scrolling content#
Use DialogBody for content that can grow. The header and footer stay visible while the body
scrolls.
import { Stack, Text } from '@orkest/ui';
import {
Dialog,
DialogBody,
DialogClose,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogOverlay,
DialogPortal,
DialogTitle,
DialogTrigger,
} from '@orkest/ui/client';
const clauses = Array.from(
{ length: 40 },
(_, index) =>
`Clause ${index + 1}. This section is long enough to demonstrate a scrollable dialog body while the header and footer stay visible. It includes additional wording so the example overflows on large screens as well.`,
);
export function Example() {
return (
<Dialog>
<DialogTrigger variant="secondary">View terms</DialogTrigger>
<DialogPortal>
<DialogOverlay />
<DialogContent size="lg">
<DialogHeader>
<DialogTitle>Service terms</DialogTitle>
<DialogDescription>
Review the full text before accepting.
</DialogDescription>
</DialogHeader>
<DialogBody>
<Stack gap={3}>
{clauses.map((clause) => (
<Text key={clause} as="p" size="sm" tone="muted">
{clause}
</Text>
))}
</Stack>
</DialogBody>
<DialogFooter>
<DialogClose>Close</DialogClose>
</DialogFooter>
</DialogContent>
</DialogPortal>
</Dialog>
);
}Close behavior#
Dialog closes on Escape and overlay press by default. Disable either path when the content should
not be dismissed accidentally:
<Dialog closeOnEscape={false} closeOnOverlayClick={false}>DialogContent renders an icon close action by default. Use showCloseButton={false} to hide it,
or closeLabel to change its accessible name.
Props#
Dialog#
| Prop | Type | Default |
|---|---|---|
open | boolean | — |
| Controlled open state. | ||
defaultOpen | boolean | false |
| Initial open state for uncontrolled usage. | ||
onOpenChange | (open, eventDetails) => void | — |
| Called when the dialog requests an open state change. | ||
modal | boolean | 'trap-focus' | true |
| Traps focus, locks page scroll, and blocks outside interaction. | ||
closeOnOverlayClick | boolean | true |
| Closes the dialog when the backdrop is pressed. | ||
closeOnEscape | boolean | true |
| Closes the dialog when Escape is pressed. | ||
onOpenChangeComplete | (open: boolean) => void | — |
| Called after the open or close animation completes. | ||
actionsRef | RefObject<{ close: () => void; unmount: () => void }> | — |
| Imperative close and unmount actions. | ||
triggerId / defaultTriggerId | string | — |
| Associates an external trigger with a controlled dialog. | ||
DialogContent#
| Prop | Type | Default |
|---|---|---|
size | 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'md' |
| Maximum width preset. `full` fills the viewport. | ||
showCloseButton | boolean | true |
| Shows the built-in icon close action. | ||
closeLabel | string | 'Close' |
| Accessible name for the built-in close action. | ||
initialFocus | boolean | RefObject<HTMLElement> | function | — |
| Element focused when the dialog opens. | ||
finalFocus | boolean | RefObject<HTMLElement> | function | — |
| Element focused when the dialog closes. | ||
native attributes | HTMLAttributes<HTMLDivElement> | — |
| Class names, data attributes, and refs are forwarded to the popup. | ||
DialogTrigger and DialogClose#
| Prop | Type | Default |
|---|---|---|
variant | 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link' | Trigger: 'primary'; Close: 'secondary' |
| Visual Button variant used by the default button. | ||
size | 'sm' | 'md' | 'lg' | 'xl' | 'md' |
| Button size. | ||
render | ReactElement | — |
| Replaces the default Button, for example with a custom Button variant. | ||
native attributes | ButtonHTMLAttributes<HTMLButtonElement> | — |
| Disabled, type, click handlers, and refs are forwarded. | ||
Layout parts#
| Prop | Type | Default |
|---|---|---|
DialogHeader | HTMLAttributes<HTMLDivElement> | — |
| Groups the title and description. | ||
DialogTitle | Base UI Dialog Title props | — |
| Accessible title. Use render to change the heading level. | ||
DialogDescription | Base UI Dialog Description props | — |
| Supporting text associated through aria-describedby. | ||
DialogBody | HTMLAttributes<HTMLDivElement> | — |
| Scrollable content region between the header and footer. | ||
DialogFooter | HTMLAttributes<HTMLDivElement> | — |
| Action row aligned to the end of the dialog. | ||
DialogOverlay | Base UI Dialog Backdrop props | — |
| Backdrop rendered beneath the dialog content. | ||
DialogPortal | Base UI Dialog Portal props | — |
| Supports a custom container and keepMounted. | ||
Accessibility#
- Render
DialogTitlefor the accessible name andDialogDescriptionfor supporting text. Base UI wiresaria-labelledbyandaria-describedbyautomatically. - Modal dialogs trap focus, lock page scroll, and restore focus to the trigger or the previously focused element when closed.
- Use
initialFocusto focus a specific field when the dialog opens. - Escape and overlay press close the dialog by default. Disable them only when the task must not be dismissed accidentally.
- The built-in close action is a labeled button (
closeLabel). Provide an accessible name when composingDialogClosewith a custom icon button. - Use
DialogBodyfor long content so the header and footer remain reachable. fulldialogs keep the same focus and keyboard behavior as smaller sizes.
Related#
- Alert Dialog for destructive or irreversible confirmations.
- Field for dialog forms.
- Button for trigger and action styling.