Skip to contents

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:

Anatomy
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.

Uncontrolled dialog
<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.

Controlled dialog
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.

Running code when dialog 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.

Detached triggers
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>.

Multiple triggers within the Root part
<Dialog.Root>
  <Dialog.Trigger>Trigger 1</Dialog.Trigger>
  <Dialog.Trigger>Trigger 2</Dialog.Trigger>
  ...
</Dialog.Root>
Multiple detached triggers
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:

Detached triggers with payload
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.

Prop
Type
Default
defaultOpenbooleanfalse
Whether the dialog is initially open. To render a controlled dialog, use the open prop instead.boolean
openboolean—
Whether the dialog is currently open.boolean
onOpenChangefunction—
Event handler called when the dialog is opened or closed.((open: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => void)
actionsRefRefObject<Dialog.Root.Actions | null>—
A ref to imperative actions. 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—
ID of the trigger that the dialog is associated with. This is useful in conjunction with the defaultOpen prop to create an initially open dialog.string | null
disablePointerDismissalbooleanfalse
Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.boolean
handleDialog.Handle<Payload>—
A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog’s open state. Can be created with the Dialog.createHandle() method.Dialog.Handle<Payload>
modalUniontrue
Determines if the dialog enters a modal state when open. 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—
Event handler called after any animations complete when the dialog is opened or closed.((open: boolean) => void)
triggerIdUnion—
ID of the trigger that the dialog is associated with. This is useful in conjunction with the 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 | null
childrenUnion—
The content of the dialog. This can be a regular Solid JSX or a render function that receives the 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.

Prop
Type
Default
handleDialog.Handle<Payload>—
A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.Dialog.Handle<Payload>
nativeButtonbooleantrue
Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).boolean
payloadPayload—
A payload to pass to the dialog when it is opened.Payload
idstring—
ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the Dialog.Root triggerId prop).string
classfunction—
CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)
stylefunction—
Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)
renderfunction—
Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name
Type
Default
data-popup-open-—
Present when the corresponding dialog is open.-
data-disabled-—
Present when the trigger is 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.

Prop
Type
Default
containerUnion—
A parent element to render the portal element into.HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null
classfunction—
CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)
stylefunction—
Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)
keepMountedbooleanfalse
Whether to keep the portal mounted in the DOM while the popup is hidden.boolean
renderfunction—
Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)
Portal.State
type DialogPortalState = {};

Backdrop

An overlay displayed beneath the popup. Renders a <div> element.

Prop
Type
Default
forceRenderbooleanfalse
Whether the backdrop is forced to render even when nested.boolean
classfunction—
CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)
stylefunction—
Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)
renderfunction—
Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name
Type
Default
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.-
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.

Prop
Type
Default
classfunction—
CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)
stylefunction—
Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)
renderfunction—
Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name
Type
Default
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.-
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;
};

A container for the dialog contents. Renders a <div> element.

Prop
Type
Default
initialFocusfunction—
Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. 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—
Determines the element to focus when the dialog is closed. 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—
CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)
stylefunction—
Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)
renderfunction—
Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name
Type
Default
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.-
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

Name
Type
Default
--nested-dialogsnumber—
Indicates how many dialogs are nested within.number
CSS 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.

Prop
Type
Default
classfunction—
CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)
stylefunction—
Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)
renderfunction—
Replace the default element with a tag name, component, or render function.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.

Prop
Type
Default
classfunction—
CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)
stylefunction—
Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)
renderfunction—
Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)
Description.State
type DialogDescriptionState = {};

Close

A button that closes the dialog. Renders a <button> element.

Prop
Type
Default
nativeButtonbooleantrue
Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).boolean
classfunction—
CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)
stylefunction—
Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)
renderfunction—
Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name
Type
Default
data-disabled-—
Present when the button is 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;