Dialog
A popup that opens on top of the entire page.
import { Dialog } from 'base-ui-solid/dialog';
import styles from './index.module.css';
export default function ExampleDialog() {
return (
<Dialog.Root>
<Dialog.Trigger class={styles.Button}>View notifications</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Popup class={styles.Popup}>
<div class={styles.Intro}>
<Dialog.Title class={styles.Title}>Notifications</Dialog.Title>
<Dialog.Description class={styles.Description}>
You are all caught up. Good job!
</Dialog.Description>
</div>
<div class={styles.Actions}>
<Dialog.Close class={styles.Button}>Close</Dialog.Close>
</div>
</Dialog.Popup>
</Dialog.Portal>
</Dialog.Root>
);
}
Usage guidelines
- Dialog doesn’t support gestures: Use Drawer when you need gesture support or snap points. A panel that slides in from the edge of the screen and doesn’t need gesture support is a positioned Dialog.
Anatomy
Import the component and assemble its parts:
import { Dialog } from 'base-ui-solid/dialog';
<Dialog.Root>
<Dialog.Trigger />
<Dialog.Portal>
<Dialog.Backdrop />
<Dialog.Viewport>
<Dialog.Popup>
<Dialog.Title />
<Dialog.Description />
<Dialog.Close />
</Dialog.Popup>
</Dialog.Viewport>
</Dialog.Portal>
</Dialog.Root>;
Examples
State
By default, Dialog is an uncontrolled component that manages its own state.
<Dialog.Root>
<Dialog.Trigger>Open</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Popup>
<Dialog.Title>Example dialog</Dialog.Title>
<Dialog.Close>Close</Dialog.Close>
</Dialog.Popup>
</Dialog.Portal>
</Dialog.Root>
Use open and onOpenChange props if you need to access or control the state of the dialog.
For example, you can control the dialog state in order to open it imperatively from another place in your app.
import { createSignal } from 'solid-js';
const [open, setOpen] = createSignal(false);
return (
<Dialog.Root open={open()} onOpenChange={setOpen}>
<Dialog.Trigger>Open</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Popup>
<form
// Close the dialog once the form data is submitted
onSubmit={async () => {
await submitData();
setOpen(false);
}}
>
...
</form>
</Dialog.Popup>
</Dialog.Portal>
</Dialog.Root>
);
It’s also common to use onOpenChange if your app needs to do something when the dialog is closed or opened. This is recommended over createEffect when reacting to state changes.
<Dialog.Root
open={open()}
onOpenChange={(open) => {
// Do stuff when the dialog is closed
if (!open) {
doStuff();
}
// Set the new state
setOpen(open);
}}
>
Open from a menu
In order to open a dialog using a menu, control the dialog state and open it imperatively using the onClick handler on the menu item.
import { createSignal } from 'solid-js';
import type { JSX } from '@solidjs/web';
import { Dialog } from 'base-ui-solid/dialog';
import { Menu } from 'base-ui-solid/menu';
import styles from './index.module.css';
export default function ExampleDialog() {
const [dialogOpen, setDialogOpen] = createSignal(false);
return (
<>
<Menu.Root>
<Menu.Trigger class={styles.Button}>
Playlist <CaretDownIcon />
</Menu.Trigger>
<Menu.Portal>
<Menu.Positioner class={styles.Positioner} sideOffset={8} align="start">
<Menu.Popup class={styles.MenuPopup}>
<Menu.Item class={styles.MenuItem}>Play</Menu.Item>
<Menu.Item class={styles.MenuItem}>Share</Menu.Item>
<Menu.Separator class={styles.Separator} />
{/* Open the dialog when the menu item is clicked */}
<Menu.Item class={styles.MenuItem} onClick={() => setDialogOpen(true)}>
Details…
</Menu.Item>
</Menu.Popup>
</Menu.Positioner>
</Menu.Portal>
</Menu.Root>
{/* Control the dialog state */}
<Dialog.Root open={dialogOpen()} onOpenChange={setDialogOpen}>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Popup class={styles.DialogPopup}>
<div class={styles.Intro}>
<Dialog.Title class={styles.Title}>Playlist details</Dialog.Title>
<Dialog.Description class={styles.Description}>
This playlist contains 24 songs and was last updated today.
</Dialog.Description>
</div>
<div class={styles.Actions}>
<Dialog.Close class={styles.Button}>Close</Dialog.Close>
</div>
</Dialog.Popup>
</Dialog.Portal>
</Dialog.Root>
</>
);
}
function CaretDownIcon(props: JSX.IntrinsicElements['svg']) {
return (
<svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="currentColor"
{...props}
style={
typeof props.style === 'string'
? `display: block; ${props.style}`
: { display: 'block', ...(typeof props.style === 'object' ? props.style : {}) }
}
>
<path d="M12 6H4l4 4.5z" />
</svg>
);
}
Nested dialogs
You can nest dialogs within one another normally.
Use the [data-nested-dialog-open] selector and the var(--nested-dialogs) CSS variable to customize the styling of the parent dialog. Backdrops of the child dialogs won’t be rendered so that you can present the parent dialog in a clean way behind the one on top of it.
import { Dialog } from 'base-ui-solid/dialog';
import styles from './index.module.css';
export default function ExampleDialog() {
return (
<Dialog.Root>
<Dialog.Trigger class={styles.Button}>View notifications</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Popup class={styles.Popup}>
<div class={styles.Intro}>
<Dialog.Title class={styles.Title}>Notifications</Dialog.Title>
<Dialog.Description class={styles.Description}>
You are all caught up. Good job!
</Dialog.Description>
</div>
<div class={styles.Actions}>
<Dialog.Root>
<Dialog.Trigger class={styles.Button}>Customize</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Popup class={styles.Popup}>
<div class={styles.Intro}>
<Dialog.Title class={styles.Title}>Customize notifications</Dialog.Title>
<Dialog.Description class={styles.Description}>
Review your settings here.
</Dialog.Description>
</div>
<div class={styles.EndActions}>
<Dialog.Close class={styles.Button}>Close</Dialog.Close>
</div>
</Dialog.Popup>
</Dialog.Portal>
</Dialog.Root>
</div>
</Dialog.Popup>
</Dialog.Portal>
</Dialog.Root>
);
}
Close confirmation
This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.
To implement this, both dialogs should be controlled. The confirmation dialog may be opened when onOpenChange callback of the parent dialog receives a request to close. This way, the confirmation is automatically shown when the user clicks the backdrop, presses the Esc key, or clicks a close button.
import { createSignal, createUniqueId } from 'solid-js';
import { AlertDialog } from 'base-ui-solid/alert-dialog';
import { Dialog } from 'base-ui-solid/dialog';
import styles from './index.module.css';
export default function ExampleDialog() {
const [dialogOpen, setDialogOpen] = createSignal(false);
const [confirmationOpen, setConfirmationOpen] = createSignal(false);
const [textareaValue, setTextareaValue] = createSignal('');
const titleId = createUniqueId();
return (
<Dialog.Root
open={dialogOpen()}
onOpenChange={(open) => {
// Show the close confirmation if there’s text in the textarea
if (!open && textareaValue()) {
setConfirmationOpen(true);
} else {
// Reset the text area value
setTextareaValue('');
// Open or close the dialog normally
setDialogOpen(open);
}
}}
>
<Dialog.Trigger class={styles.Button}>Tweet</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Popup class={styles.Popup}>
<div class={styles.PopupBody}>
<Dialog.Title id={titleId} class={styles.Title}>
New tweet
</Dialog.Title>
<form
class={styles.TextareaContainer}
onSubmit={(event) => {
event.preventDefault();
// Close the dialog when submitting
setDialogOpen(false);
}}
>
<textarea
aria-labelledby={titleId}
required
class={styles.Textarea}
placeholder="What’s on your mind?"
value={textareaValue()}
onInput={(event) => setTextareaValue(event.target.value)}
/>
<div class={styles.Actions}>
<Dialog.Close class={styles.Button}>Cancel</Dialog.Close>
<button type="submit" class={styles.Button}>
Tweet
</button>
</div>
</form>
</div>
</Dialog.Popup>
</Dialog.Portal>
{/* Confirmation dialog */}
<AlertDialog.Root open={confirmationOpen()} onOpenChange={setConfirmationOpen}>
<AlertDialog.Portal>
<AlertDialog.Popup class={styles.Popup}>
<div class={styles.Intro}>
<AlertDialog.Title class={styles.Title}>Discard tweet?</AlertDialog.Title>
<AlertDialog.Description class={styles.Description}>
Your tweet will be lost.
</AlertDialog.Description>
</div>
<div class={styles.Actions}>
<AlertDialog.Close class={styles.Button}>Go back</AlertDialog.Close>
<button
type="button"
class={styles.Button}
onClick={() => {
setConfirmationOpen(false);
setDialogOpen(false);
}}
>
Discard
</button>
</div>
</AlertDialog.Popup>
</AlertDialog.Portal>
</AlertDialog.Root>
</Dialog.Root>
);
}
Custom focus management
You can control where the focus goes when the dialog opens and closes using the initialFocus and finalFocus props on the <Dialog.Popup> component.
You can also set these props to false to prevent focus from moving when the dialog opens or closes, or to a function that returns the element to focus based on the interaction type.
import { Dialog } from 'base-ui-solid/dialog';
import { Field } from 'base-ui-solid/field';
import { Fieldset } from 'base-ui-solid/fieldset';
import styles from './index.module.css';
export default function ExampleDialog() {
const initialFocusRef = { current: null } as { current: HTMLInputElement | null };
const finalFocusRef = { current: null } as { current: HTMLButtonElement | null };
return (
<div class={styles.Container}>
<Dialog.Root>
<Dialog.Trigger class={styles.Button}>Open feedback</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Popup
class={styles.Popup}
initialFocus={() => initialFocusRef.current}
finalFocus={() => finalFocusRef.current}
>
<div class={styles.Intro}>
<Dialog.Title class={styles.Title}>Feedback form</Dialog.Title>
<Dialog.Description class={styles.Description}>
Your feedback means a lot to us.
</Dialog.Description>
</div>
<Fieldset.Root class={styles.Fieldset}>
<Field.Root class={styles.Field}>
<Field.Label class={styles.Label}>Full name</Field.Label>
<Field.Control placeholder="Enter your name" class={styles.Input} />
</Field.Root>
<Field.Root class={styles.Field}>
<Field.Label class={styles.Label}>Feedback</Field.Label>
<Field.Control
ref={(element) => {
initialFocusRef.current = element as HTMLInputElement;
}}
required
placeholder="Enter your feedback"
class={styles.Input}
/>
</Field.Root>
</Fieldset.Root>
<div class={styles.Actions}>
<Dialog.Close class={styles.Button}>Close</Dialog.Close>
</div>
</Dialog.Popup>
</Dialog.Portal>
</Dialog.Root>
<button
ref={(element) => {
finalFocusRef.current = element;
}}
type="button"
class={styles.Button}
>
Final focus
</button>
</div>
);
}
Outside scroll dialog
The dialog can be made scrollable by using <Dialog.Viewport> as an outer scrollable container for <Dialog.Popup> while the popup can extend past the bottom edge. The scrollable area uses the Scroll Area component to provide custom scrollbars.
import { For } from 'solid-js';
import type { JSX } from '@solidjs/web';
import { Dialog } from 'base-ui-solid/dialog';
import { ScrollArea } from 'base-ui-solid/scroll-area';
import styles from './index.module.css';
export default function OutsideScrollDialog() {
const popupRef = { current: null } as { current: HTMLDivElement | null };
return (
<Dialog.Root>
<Dialog.Trigger class={styles.Button}>Open dialog</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Viewport class={styles.Viewport}>
<ScrollArea.Root style={{ position: undefined }} class={styles.ScrollViewport}>
<ScrollArea.Viewport class={styles.ScrollViewport}>
<ScrollArea.Content class={styles.ScrollContent}>
<Dialog.Popup
ref={(element) => {
popupRef.current = element;
}}
class={styles.Popup}
initialFocus={() => popupRef.current}
>
<div class={styles.PopupHeader}>
<Dialog.Title class={styles.Title}>Dialog</Dialog.Title>
<Dialog.Description class={styles.Description}>
This layout keeps an outer container scrollable while the dialog can extend
past the bottom edge.
</Dialog.Description>
<Dialog.Close class={styles.Close} aria-label="Close">
<XIcon />
</Dialog.Close>
</div>
<div class={styles.Body}>
<For each={CONTENT_SECTIONS}>
{(item) => (
<section class={styles.Section}>
<h3 class={styles.SectionTitle}>{item.title}</h3>
<p class={styles.SectionBody}>{item.body}</p>
</section>
)}
</For>
</div>
<p class={styles.FooterNote}>
Related docs:{' '}
<For each={RELATED_LINKS}>
{(item, index) => (
<>
{index() > 0 ? ', ' : null}
<a class={styles.FooterLink} href={item.href}>
{item.label}
</a>
</>
)}
</For>
.
</p>
</Dialog.Popup>
</ScrollArea.Content>
</ScrollArea.Viewport>
<ScrollArea.Scrollbar class={styles.Scrollbar}>
<ScrollArea.Thumb class={styles.ScrollbarThumb} />
</ScrollArea.Scrollbar>
</ScrollArea.Root>
</Dialog.Viewport>
</Dialog.Portal>
</Dialog.Root>
);
}
function XIcon(props: JSX.IntrinsicElements['svg']) {
return (
<svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
stroke="currentColor"
stroke-linecap="square"
stroke-linejoin="round"
{...props}
style={
typeof props.style === 'string'
? `display: block; ${props.style}`
: { display: 'block', ...(typeof props.style === 'object' ? props.style : {}) }
}
>
<path d="m2.5 2.5 11 11m-11 0 11-11" />
</svg>
);
}
const CONTENT_SECTIONS = [
{
title: 'What a dialog is for',
body: 'Use a dialog when you need the user to complete a focused task or read something important without navigating away. It opens on top of the page and returns focus back where it started when closed.',
},
{
title: 'Anatomy at a glance',
body: 'Root, Trigger, Portal, Backdrop, Viewport, Popup, Title, Description, Close. Keep the title short and the first paragraph specific so screen readers announce something meaningful.',
},
{
title: 'Opening and closing',
body: 'Control it using external state via the `open` and `onOpenChange` props, or let it manage state for you internally.',
},
{
title: 'Keyboard and focus behavior',
body: 'Focus moves inside the dialog when it opens. Tab and Shift+Tab loop within, and Esc requests close.',
},
{
title: 'Accessible labeling',
body: 'Set an explicit title and description using the `Dialog.Title` and `Dialog.Description` components.',
},
{
title: 'Backdrop and page scrolling',
body: 'The backdrop visually separates layers while background content is inert. Don’t rely on dimness alone—keep copy clear and buttons obvious so actions are easy to choose.',
},
{
title: 'Portals and stacking',
body: 'Dialogs render in a portal so they sit above the `isolation: isolate` app content and avoid local z-index wars.',
},
{
title: 'Viewport overflow',
body: 'Let long content overflow the bottom edge and reveal as you scroll the page container. Keep generous padding at the top and bottom so the dialog doesn’t feel jammed against the edges.',
},
{
title: 'Nested dialogs and confirmations',
body: 'If closing a dialog needs confirmation, open a child alert dialog rather than mutating the current one. The parent stays visible behind it; only the topmost layer should feel interactive.',
},
{
title: 'Transitions that respect motion settings',
body: 'Use small, fast transitions (opacity plus a few pixels of Y translation or scale). Subtle motion helps people notice what changed without slowing them down.',
},
{
title: 'Controlled vs. uncontrolled',
body: 'Controlled state is best when other parts of the page need to react to open/close. Uncontrolled is fine for local cases where only the dialog matters.',
},
{
title: 'Close affordances',
body: 'Always offer a visible close button in the corner. Don’t rely only on Esc or the backdrop for pointer outside presses. Touch screen readers and accessibility users benefit from a clear, targetable control to click to close the dialog.',
},
{
title: 'Forms inside dialogs',
body: 'Keep forms short; longer flows usually deserve a full page. Validate inline, keep button text specific (“Create project”), and disable destructive actions until the input is valid.',
},
{
title: 'Content guidelines',
body: 'Lead with the outcome (“Rename project?”) and follow with one or two short, concrete sentences. Avoid long prose; link out for details instead.',
},
{
title: 'SSR and hydration notes',
body: 'Because dialogs render in a portal, make sure your portal container exists on the client.',
},
{
title: 'Mobile ergonomics',
body: 'Use larger touch targets and keep the close button reachable with the thumb. Avoid full-screen modals unless the task truly needs a whole screen.',
},
{
title: 'Theming and density',
body: 'Match spacing and corner radius to your system. Use a slightly denser layout than pages so the dialog feels purpose-built, not like a mini web page.',
},
{
title: 'Internationalization',
body: 'Plan for longer text. Buttons can grow to two lines; titles should wrap gracefully. Keep destructive terms consistent across locales.',
},
{
title: 'Performance',
body: 'Children are mounted lazily when the dialog opens. If the dialog can reopen often, consider the `keepMounted` prop sparingly to perform the work only once on mount to avoid re-initializing complex React trees on each open.',
},
{
title: 'When a popover is better',
body: 'If the content is a small hint or a few quick actions anchored to a control, use a popover or menu instead of a dialog. Dialogs interrupt on purpose—use that sparingly.',
},
{
title: 'Follow-up and cleanup',
body: 'After a successful action, close the dialog and show confirmation in context (toast, inline message, or updated UI) so people can see the result of what they just did.',
},
];
const RELATED_LINKS = [
{ href: '/solid/components/scroll-area', label: 'Scroll Area' },
{ href: '/solid/components/drawer', label: 'Drawer' },
{ href: '/solid/components/popover', label: 'Popover' },
] as const;
Inside scroll dialog
The dialog can be made scrollable by making an inner container scrollable while the popup stays fully on screen. <Dialog.Viewport> is used as a positioning container for <Dialog.Popup>, while an inner scrollable area is created using the Scroll Area component.
import { For } from 'solid-js';
import { Dialog } from 'base-ui-solid/dialog';
import { ScrollArea } from 'base-ui-solid/scroll-area';
import styles from './index.module.css';
export default function InsideScrollDialog() {
return (
<Dialog.Root>
<Dialog.Trigger class={styles.Button}>Open dialog</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Viewport class={styles.Viewport}>
<Dialog.Popup class={styles.Popup}>
<div class={styles.Header}>
<Dialog.Title class={styles.Title}>Dialog</Dialog.Title>
<Dialog.Description class={styles.Description}>
This layout keeps the popup fully on screen while allowing its content to scroll.
</Dialog.Description>
</div>
<ScrollArea.Root class={styles.Body}>
<ScrollArea.Viewport class={styles.BodyViewport}>
<ScrollArea.Content class={styles.BodyContent}>
<For each={CONTENT_SECTIONS}>
{(item) => (
<section class={styles.Section}>
<h3 class={styles.SectionTitle}>{item.title}</h3>
<p class={styles.SectionBody}>{item.body}</p>
</section>
)}
</For>
</ScrollArea.Content>
</ScrollArea.Viewport>
<ScrollArea.Scrollbar class={styles.Scrollbar}>
<ScrollArea.Thumb class={styles.ScrollbarThumb} />
</ScrollArea.Scrollbar>
</ScrollArea.Root>
<div class={styles.Actions}>
<Dialog.Close class={styles.Button}>Close</Dialog.Close>
</div>
</Dialog.Popup>
</Dialog.Viewport>
</Dialog.Portal>
</Dialog.Root>
);
}
const CONTENT_SECTIONS = [
{
title: 'What a dialog is for',
body: 'Use a dialog when you need the user to complete a focused task or read something important without navigating away. It opens on top of the page and returns focus back where it started when closed.',
},
{
title: 'Anatomy at a glance',
body: 'Root, Trigger, Portal, Backdrop, Popup, Title/Description, Close. Keep the title short and the first paragraph specific so screen readers announce something meaningful.',
},
{
title: 'Opening and closing',
body: 'Control it using external state via the `open` and `onOpenChange` props, or let it manage state for you internally.',
},
{
title: 'Keyboard and focus behavior',
body: 'Focus moves inside the dialog when it opens. Tab and Shift+Tab loop within, and Esc requests close.',
},
{
title: 'Accessible labeling',
body: 'Set an explicit title and description using the `Dialog.Title` and `Dialog.Description` components.',
},
{
title: 'Backdrop and page scrolling',
body: 'The backdrop visually separates layers while background content is inert. Don’t rely on dimness alone—keep copy clear and buttons obvious so actions are easy to choose.',
},
{
title: 'Portals and stacking',
body: 'Dialogs render in a portal so they sit above the `isolation: isolate` app content and avoid local z-index wars.',
},
{
title: 'Viewport overflow',
body: 'Let long content overflow the bottom edge and reveal as you scroll the page container. Keep generous padding at the top and bottom so the dialog doesn’t feel jammed against the edges.',
},
{
title: 'Nested dialogs and confirmations',
body: 'If closing a dialog needs confirmation, open a child alert dialog rather than mutating the current one. The parent stays visible behind it; only the topmost layer should feel interactive.',
},
{
title: 'Transitions that respect motion settings',
body: 'Use small, fast transitions (opacity plus a few pixels of Y translation or scale). Subtle motion helps people notice what changed without slowing them down.',
},
{
title: 'Controlled vs. uncontrolled',
body: 'Controlled state is best when other parts of the page need to react to open/close. Uncontrolled is fine for local cases where only the dialog matters.',
},
{
title: 'Close affordances',
body: 'Always offer a visible close button in the corner. Don’t rely only on Esc or the backdrop for pointer outside presses. Touch screen readers and accessibility users benefit from a clear, targetable control to click to close the dialog.',
},
{
title: 'Forms inside dialogs',
body: 'Keep forms short; longer flows usually deserve a full page. Validate inline, keep button text specific (“Create project”), and disable destructive actions until the input is valid.',
},
{
title: 'Content guidelines',
body: 'Lead with the outcome (“Rename project?”) and follow with one or two short, concrete sentences. Avoid long prose; link out for details instead.',
},
{
title: 'SSR and hydration notes',
body: 'Because dialogs render in a portal, make sure your portal container exists on the client.',
},
{
title: 'Mobile ergonomics',
body: 'Use larger touch targets and keep the close button reachable with the thumb. Avoid full-screen modals unless the task truly needs a whole screen.',
},
{
title: 'Theming and density',
body: 'Match spacing and corner radius to your system. Use a slightly denser layout than pages so the dialog feels purpose-built, not like a mini web page.',
},
{
title: 'Internationalization',
body: 'Plan for longer text. Buttons can grow to two lines; titles should wrap gracefully. Keep destructive terms consistent across locales.',
},
{
title: 'Performance',
body: 'Children are mounted lazily when the dialog opens. If the dialog can reopen often, consider the `keepMounted` prop sparingly to perform the work only once on mount to avoid re-initializing complex React trees on each open.',
},
{
title: 'When a popover is better',
body: 'If the content is a small hint or a few quick actions anchored to a control, use a popover or menu instead of a dialog. Dialogs interrupt on purpose—use that sparingly.',
},
{
title: 'Follow-up and cleanup',
body: 'After a successful action, close the dialog and show confirmation in context (toast, inline message, or updated UI) so people can see the result of what they just did.',
},
];
Placing elements outside the popup
When adding elements that should appear “outside” the colored popup area, continue to place them inside <Dialog.Popup>, but create a child element that has the popup styles. This ensures they are kept in the tab order and announced correctly by screen readers.
<Dialog.Popup> has pointer-events: none, while inner content (the colored popup and close button) has pointer-events: auto so clicks on the backdrop continue to be registered.
import type { JSX } from '@solidjs/web';
import { Dialog } from 'base-ui-solid/dialog';
import styles from './index.module.css';
export default function ExampleUncontainedDialog() {
return (
<Dialog.Root>
<Dialog.Trigger class={styles.Button}>Open dialog</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Viewport class={styles.Viewport}>
<Dialog.Popup class={styles.PopupRoot}>
<Dialog.Close class={styles.Close} aria-label="Close">
<XIcon />
</Dialog.Close>
<div class={styles.Popup} />
</Dialog.Popup>
</Dialog.Viewport>
</Dialog.Portal>
</Dialog.Root>
);
}
function XIcon(props: JSX.IntrinsicElements['svg']) {
return (
<svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
stroke="currentColor"
stroke-linecap="square"
stroke-linejoin="round"
{...props}
style={
typeof props.style === 'string'
? `display: block; ${props.style}`
: { display: 'block', ...(typeof props.style === 'object' ? props.style : {}) }
}
>
<path d="m2.5 2.5 11 11m-11 0 11-11" />
</svg>
);
}
Detached triggers
A dialog can be controlled by a trigger located either inside or outside the <Dialog.Root> component.
For simple, one-off interactions, place the <Dialog.Trigger> inside <Dialog.Root>, as shown in the example at the top of this page.
However, if defining the dialog’s content next to its trigger is not practical, you can use a detached trigger.
This involves placing the <Dialog.Trigger> outside of <Dialog.Root> and linking them with a handle created by the Dialog.createHandle() function.
The imperative methods on the handle, such as open() and openWithPayload(), require a <Dialog.Root> using the same handle to be mounted.
Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.
const demoDialog = Dialog.createHandle();
<Dialog.Trigger handle={demoDialog}>Open</Dialog.Trigger>
<Dialog.Root handle={demoDialog}>
...
</Dialog.Root>
import { Dialog } from 'base-ui-solid/dialog';
import styles from './index.module.css';
const demoDialog = Dialog.createHandle();
export default function DialogDetachedTriggersSimpleDemo() {
return (
<>
<Dialog.Trigger class={styles.Button} handle={demoDialog}>
View notifications
</Dialog.Trigger>
<Dialog.Root handle={demoDialog}>
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Popup class={styles.Popup}>
<div class={styles.Intro}>
<Dialog.Title class={styles.Title}>Notifications</Dialog.Title>
<Dialog.Description class={styles.Description}>
You are all caught up. Good job!
</Dialog.Description>
</div>
<div class={styles.Actions}>
<Dialog.Close class={styles.Button}>Close</Dialog.Close>
</div>
</Dialog.Popup>
</Dialog.Portal>
</Dialog.Root>
</>
);
}
Multiple triggers
A single dialog can be opened by multiple trigger elements.
You can achieve this by using the same handle for several detached triggers, or by placing multiple <Dialog.Trigger> components inside a single <Dialog.Root>.
<Dialog.Root>
<Dialog.Trigger>Trigger 1</Dialog.Trigger>
<Dialog.Trigger>Trigger 2</Dialog.Trigger>
...
</Dialog.Root>
const demoDialog = Dialog.createHandle();
<Dialog.Trigger handle={demoDialog}>Trigger 1</Dialog.Trigger>
<Dialog.Trigger handle={demoDialog}>Trigger 2</Dialog.Trigger>
<Dialog.Root handle={demoDialog}>
...
</Dialog.Root>
The dialog can render different content depending on which trigger opened it.
This is achieved by passing a payload to the <Dialog.Trigger> and using the function-as-a-child pattern in <Dialog.Root>.
The payload can be strongly typed by providing a type argument to the createHandle() function:
const demoDialog = Dialog.createHandle<{ text: string }>();
<Dialog.Trigger handle={demoDialog} payload={{ text: 'Trigger 1' }}>
Trigger 1
</Dialog.Trigger>
<Dialog.Trigger handle={demoDialog} payload={{ text: 'Trigger 2' }}>
Trigger 2
</Dialog.Trigger>
<Dialog.Root handle={demoDialog}>
{({ payload }) => (
<Dialog.Portal>
<Dialog.Popup>
<Dialog.Title>Dialog</Dialog.Title>
{payload !== undefined && (
<Dialog.Description>
This has been opened by {payload.text}
</Dialog.Description>
)}
</Dialog.Popup>
</Dialog.Portal>
)}
</Dialog.Root>
Controlled mode with multiple triggers
You can control the dialog’s open state externally using the open and onOpenChange props on <Dialog.Root>.
This allows you to manage the dialog’s visibility based on your application’s state.
When using multiple triggers, you have to manage which trigger is active with the triggerId prop on <Dialog.Root> and the id prop on each <Dialog.Trigger>.
Note that there is no separate onTriggerIdChange prop.
Instead, the onOpenChange callback receives an additional argument, eventDetails, which contains the trigger element that initiated the state change.
import { createSignal } from 'solid-js';
import { Dialog } from 'base-ui-solid/dialog';
import styles from './index.module.css';
const demoDialog = Dialog.createHandle<number>();
export default function DialogDetachedTriggersControlledDemo() {
const [open, setOpen] = createSignal(false);
const [triggerId, setTriggerId] = createSignal<string | null>(null);
const handleOpenChange = (isOpen: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => {
setOpen(isOpen);
setTriggerId(eventDetails.trigger?.id ?? null);
};
return (
<>
<div class={styles.Container}>
<Dialog.Trigger class={styles.Button} handle={demoDialog} id="trigger-1" payload={1}>
Open 1
</Dialog.Trigger>
<Dialog.Trigger class={styles.Button} handle={demoDialog} id="trigger-2" payload={2}>
Open 2
</Dialog.Trigger>
<Dialog.Trigger class={styles.Button} handle={demoDialog} id="trigger-3" payload={3}>
Open 3
</Dialog.Trigger>
<button
class={styles.Button}
type="button"
onClick={() => {
setTriggerId('trigger-2');
setOpen(true);
}}
>
Open programmatically
</button>
</div>
<Dialog.Root
handle={demoDialog}
open={open()}
onOpenChange={handleOpenChange}
triggerId={triggerId()}
>
{(state) => (
<Dialog.Portal>
<Dialog.Backdrop class={styles.Backdrop} />
<Dialog.Popup class={styles.Popup}>
{state.payload !== undefined && (
<Dialog.Title class={styles.Title}>Dialog {state.payload}</Dialog.Title>
)}
<div class={styles.Actions}>
<Dialog.Close class={styles.Button}>Close</Dialog.Close>
</div>
</Dialog.Popup>
</Dialog.Portal>
)}
</Dialog.Root>
</>
);
}
API reference
Root
Groups all parts of the dialog. Doesn’t render its own HTML element.
defaultOpenbooleanfalse
open prop instead.booleanopenboolean—
booleanonOpenChangefunction—
((open: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => void)actionsRefRefObject<Dialog.Root.Actions | null>—
unmount: Ends the closing phase of the dialog after an externally controlled closing animation finishes.
Call preventUnmountOnClose() in onOpenChange first, otherwise the dialog completes closing on its own.
Whether it leaves the DOM is decided by keepMounted on the portal.close: Closes the dialog imperatively when called.RefObject<Dialog.Root.Actions | null>defaultTriggerIdUnion—
defaultOpen prop to create an initially open dialog.string | nulldisablePointerDismissalbooleanfalse
booleanhandleDialog.Handle<Payload>—
Dialog.Handle<Payload>modalUniontrue
true: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.false: user interaction with the rest of the document is allowed.'trap-focus': focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. When modal is true or 'trap-focus', render <Dialog.Close> inside <Dialog.Popup> so
touch screen readers can escape the popup.boolean | 'trap-focus'onOpenChangeCompletefunction—
((open: boolean) => void)triggerIdUnion—
open prop to create a controlled dialog.
There’s no need to specify this prop when the dialog is uncontrolled (that is, when the open prop is not set).string | nullchildrenUnion—
payload of the active trigger.JSX.Element | PayloadChildRenderFunction<Payload>Root.State
type DialogRootState = {};Root.Actions
type DialogRootActions = { unmount: () => void; close: () => void };Root.ChangeEventReason
type DialogRootChangeEventReason =
| 'trigger-press'
| 'outside-press'
| 'escape-key'
| 'close-press'
| 'focus-out'
| 'imperative-action'
| 'none';Root.ChangeEventDetails
type DialogRootChangeEventDetails = (
| { reason: 'trigger-press'; event: KeyboardEvent | MouseEvent | TouchEvent | PointerEvent }
| { reason: 'outside-press'; event: MouseEvent | TouchEvent | PointerEvent }
| { reason: 'escape-key'; event: KeyboardEvent }
| { reason: 'close-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
| { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
| { reason: 'imperative-action'; event: Event }
| { reason: 'none'; event: Event }
) & {
/** Cancels Base UI from handling the event. */
cancel: () => void;
/** Allows the event to propagate in cases where Base UI will stop the propagation. */
allowPropagation: () => void;
/** Indicates whether the event has been canceled. */
isCanceled: boolean;
/** Indicates whether the event is allowed to propagate. */
isPropagationAllowed: boolean;
/** The element that triggered the event, if applicable. */
trigger: Element | undefined;
/** Prevents the popup from unmounting until the `unmount` action is called. */
preventUnmountOnClose: () => void;
};Trigger
A button that opens the dialog.
Renders a <button> element.
handleDialog.Handle<Payload>—
Dialog.Handle<Payload>nativeButtonbooleantrue
<button> element when replacing it
via the render prop.
Set to false if the rendered element is not a button (for example, <div>).booleanpayloadPayload—
Payloadidstring—
triggerId prop).stringclassfunction—
JSX.ClassValue | ((state) => JSX.ClassValue)stylefunction—
JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)renderfunction—
keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)Data attributes
data-popup-open-—
-data-disabled-—
-Attribute | Description | |
|---|---|---|
data-popup-open | Present when the corresponding dialog is open. | |
data-disabled | Present when the trigger is disabled. | |
Trigger.State
type DialogTriggerState = {
/** Whether the trigger is currently disabled. */
disabled: boolean;
/** Whether the dialog is currently open and was opened by this trigger. */
open: boolean;
};Portal
A portal element that moves the popup to a different part of the DOM.
By default, the portal element is appended to <body>.
Renders a <div> element.
containerUnion—
HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | nullclassfunction—
JSX.ClassValue | ((state) => JSX.ClassValue)stylefunction—
JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)keepMountedbooleanfalse
booleanrenderfunction—
keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)Portal.State
type DialogPortalState = {};Backdrop
An overlay displayed beneath the popup.
Renders a <div> element.
forceRenderbooleanfalse
booleanclassfunction—
JSX.ClassValue | ((state) => JSX.ClassValue)stylefunction—
JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)renderfunction—
keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)Data attributes
data-open-—
-data-closed-—
-data-starting-style-—
-data-ending-style-—
-Attribute | Description | |
|---|---|---|
data-open | Present when the dialog is open. | |
data-closed | Present when the dialog is closed. | |
data-starting-style | Present when the dialog begins animating in. | |
data-ending-style | Present when the dialog is animating out. | |
Backdrop.State
type DialogBackdropState = {
/** Whether the dialog is currently open. */
open: boolean;
/** The transition status of the component. */
transitionStatus: TransitionStatus;
};Viewport
A positioning container for the dialog popup that can be made scrollable.
Renders a <div> element.
classfunction—
JSX.ClassValue | ((state) => JSX.ClassValue)stylefunction—
JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)renderfunction—
keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)Data attributes
data-open-—
-data-closed-—
-data-nested-—
-data-nested-dialog-open-—
-data-starting-style-—
-data-ending-style-—
-Attribute | Description | |
|---|---|---|
data-open | Present when the dialog is open. | |
data-closed | Present when the dialog is closed. | |
data-nested | Present when the dialog is nested within another dialog. | |
data-nested-dialog-open | Present when the dialog has other open dialogs nested within it. | |
data-starting-style | Present when the dialog begins animating in. | |
data-ending-style | Present when the dialog is animating out. | |
Viewport.State
type DialogViewportState = {
/** Whether the dialog is currently open. */
open: boolean;
/** The transition status of the component. */
transitionStatus: TransitionStatus;
/** Whether the dialog is nested within another dialog. */
nested: boolean;
/** Whether the dialog has nested dialogs open. */
nestedDialogOpen: boolean;
};Popup
A container for the dialog contents.
Renders a <div> element.
initialFocusfunction—
false: Do not move focus.true: Move focus based on the default behavior (first tabbable element or popup).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse, touch, pen, or keyboard).
Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)finalFocusfunction—
false: Do not move focus.true: Move focus based on the default behavior (trigger or previously focused element).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse, touch, pen, or keyboard).
Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)classfunction—
JSX.ClassValue | ((state) => JSX.ClassValue)stylefunction—
JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)renderfunction—
keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)Data attributes
data-open-—
-data-closed-—
-data-nested-—
-data-nested-dialog-open-—
-data-starting-style-—
-data-ending-style-—
-Attribute | Description | |
|---|---|---|
data-open | Present when the dialog is open. | |
data-closed | Present when the dialog is closed. | |
data-nested | Present when the dialog is nested within another dialog. | |
data-nested-dialog-open | Present when the dialog has other open dialogs nested within it. | |
data-starting-style | Present when the dialog begins animating in. | |
data-ending-style | Present when the dialog is animating out. | |
CSS variables
--nested-dialogsnumber—
numberCSS Variable | Description | |
|---|---|---|
--nested-dialogs | Indicates how many dialogs are nested within. | |
Popup.State
type DialogPopupState = {
/** Whether the dialog is currently open. */
open: boolean;
/** The transition status of the component. */
transitionStatus: TransitionStatus;
/** Whether the dialog is nested within a parent dialog. */
nested: boolean;
/** Whether the dialog has nested dialogs open. */
nestedDialogOpen: boolean;
};Title
A heading that labels the dialog.
Renders an <h2> element.
classfunction—
JSX.ClassValue | ((state) => JSX.ClassValue)stylefunction—
JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)renderfunction—
keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)Title.State
type DialogTitleState = {};Description
A paragraph with additional information about the dialog.
Renders a <p> element.
classfunction—
JSX.ClassValue | ((state) => JSX.ClassValue)stylefunction—
JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)renderfunction—
keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)Description.State
type DialogDescriptionState = {};Close
A button that closes the dialog.
Renders a <button> element.
nativeButtonbooleantrue
<button> element when replacing it
via the render prop.
Set to false if the rendered element is not a button (for example, <div>).booleanclassfunction—
JSX.ClassValue | ((state) => JSX.ClassValue)stylefunction—
JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)renderfunction—
keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)Data attributes
data-disabled-—
-Attribute | Description | |
|---|---|---|
data-disabled | Present when the button is disabled. | |
Close.State
type DialogCloseState = {
/** Whether the button is currently disabled. */
disabled: boolean;
};createHandle
Creates a new handle to connect a Dialog.Root with detached Dialog.Trigger components.
createHandle
type ReturnValue = Dialog.Handle<Payload>;
Handle
Controls a Dialog imperatively and associates detached Dialog.Trigger components with a
Dialog.Root. Create one with Dialog.createHandle() and pass it to the handle prop of the
root and of any triggers rendered outside of it.
The imperative methods take effect only while a root using this handle is mounted; calls made
before a root attaches (or after it unmounts) are ignored.
Handle
function open(triggerId: string | null): void;
Handle
function openWithPayload(payload: Payload): void;
Handle
function close(): void;