Dialog component

import { Dialog } from 'gnome-ui/dialog';
import { Bell, User, Mail, Lock, ExternalLink, X } from 'lucide-react';

export function DialogDefault() {
  return (
    <Dialog.Root>
      <Dialog.Trigger className="inline-flex items-center justify-center gap-2 rounded-xl text-sm font-medium leading-none transition-colors duration-150 focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 h-9 border border-border bg-card px-4 text-foreground hover:bg-accent">
        <Icons.Bell className="size-4 shrink-0" />
        View notifications
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black/40 backdrop-blur-sm transition-all duration-200 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 supports-[-webkit-touch-callout:none]:absolute" />
        <Dialog.Popup className="fixed top-1/2 left-1/2 w-[400px] max-w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-hidden rounded-xl border border-border bg-card shadow-xl outline-none transition-all duration-200 data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0">
          <div className="flex items-center gap-3 border-b border-border px-5 py-4">
            <Icons.Bell className="size-4 shrink-0 text-primary" />
            <Dialog.Title className="flex-1 text-base font-semibold text-foreground">
              Notifications
            </Dialog.Title>
            <Dialog.Close className="flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring">
              <Icons.X className="size-4" />
            </Dialog.Close>
          </div>

          <div className="flex flex-col divide-y divide-border">
            {[
              { icon: Icons.User,         label: 'Marco joined your workspace',  time: '2m ago',  read: false },
              { icon: Icons.Mail,         label: 'New message from Sara',         time: '14m ago', read: false },
              { icon: Icons.ExternalLink, label: 'Build pipeline completed',      time: '1h ago',  read: true  },
              { icon: Icons.Lock,         label: 'Password changed successfully', time: '3h ago',  read: true  },
            ].map(({ icon: Icon, label, time, read }) => (
              <div key={label} className={`flex items-start gap-3 px-5 py-3.5 ${read ? 'opacity-60' : ''}`}>
                <div className={`mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-full ${read ? 'bg-muted text-muted-foreground' : 'bg-primary/10 text-primary'}`}>
                  <Icon className="size-3.5" />
                </div>
                <div className="flex-1 min-w-0">
                  <p className="text-sm text-foreground">{label}</p>
                  <p className="mt-0.5 text-xs text-muted-foreground">{time}</p>
                </div>
                {!read && <span className="mt-2 h-1.5 w-1.5 shrink-0 rounded-full bg-primary" />}
              </div>
            ))}
          </div>

          <div className="flex justify-end border-t border-border px-5 py-3">
            <Dialog.Close className="inline-flex items-center justify-center gap-2 rounded-xl text-sm font-medium leading-none transition-colors duration-150 focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 h-9 bg-primary px-4 text-primary-foreground hover:brightness-95">
              Mark all as read
            </Dialog.Close>
          </div>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Anatomy

import { Dialog } from 'gnome-ui/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

Settings / Form

A dialog with form inputs for editing user profile data, inspired by GNOME Settings modals.

Dialog component

import { Dialog } from 'gnome-ui/dialog';
import { Settings, User, Mail, X, Pencil } from 'lucide-react';

export function DialogSettings() {
  return (
    <Dialog.Root>
      <Dialog.Trigger className="inline-flex items-center justify-center gap-2 rounded-xl text-sm font-medium leading-none transition-colors duration-150 focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 h-9 border border-border bg-card px-4 text-foreground hover:bg-accent">
        <Icons.Settings className="size-4 shrink-0" />
        Edit profile
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black/40 backdrop-blur-sm transition-all duration-200 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 supports-[-webkit-touch-callout:none]:absolute" />
        <Dialog.Popup className="fixed top-1/2 left-1/2 w-[440px] max-w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-hidden rounded-xl border border-border bg-card shadow-xl outline-none transition-all duration-200 data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0">
          <div className="flex items-center gap-3 border-b border-border px-5 py-4">
            <Icons.Pencil className="size-4 shrink-0 text-primary" />
            <Dialog.Title className="flex-1 text-base font-semibold text-foreground">
              Edit profile
            </Dialog.Title>
            <Dialog.Close className="flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring">
              <Icons.X className="size-4" />
            </Dialog.Close>
          </div>

          <div className="flex flex-col gap-4 px-5 py-5">
            <Dialog.Description className="text-sm leading-relaxed text-muted-foreground">
              Update your public profile information. Changes will be visible to all workspace members.
            </Dialog.Description>

            {[
              { label: 'Full name', placeholder: 'Elena Larsson', icon: Icons.User },
              { label: 'Email address', placeholder: 'elena@example.com', icon: Icons.Mail },
            ].map(({ label, placeholder, icon: Icon }) => (
              <div key={label} className="flex flex-col gap-1.5">
                <label className="text-xs font-semibold uppercase tracking-widest text-muted-foreground">
                  {label}
                </label>
                <div className="relative flex items-center">
                  <Icon className="pointer-events-none absolute left-3 size-4 text-muted-foreground" />
                  <input
                    placeholder={placeholder}
                    className="h-10 w-full rounded-xl border border-input bg-background pl-9 pr-3.5 text-sm text-foreground placeholder:text-muted-foreground transition-colors duration-150 hover:border-ring/50 focus:outline focus:outline-2 focus:-outline-offset-1 focus:outline-ring"
                  />
                </div>
              </div>
            ))}
          </div>

          <div className="flex justify-end gap-2 border-t border-border px-5 py-3">
            <Dialog.Close className="inline-flex items-center justify-center gap-2 rounded-xl text-sm font-medium leading-none transition-colors duration-150 focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 h-9 border border-border bg-card px-4 text-foreground hover:bg-accent">
              Cancel
            </Dialog.Close>
            <Dialog.Close className="inline-flex items-center justify-center gap-2 rounded-xl text-sm font-medium leading-none transition-colors duration-150 focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 h-9 bg-primary px-4 text-primary-foreground hover:brightness-95">
              Save changes
            </Dialog.Close>
          </div>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Uses modal={false} so the rest of the page stays interactive. The panel slides in from the right, inspired by GNOME Files properties sidebar.

Dialog component

import { Dialog } from 'gnome-ui/dialog';
import { ExternalLink, Lock, X } from 'lucide-react';

const rows = [
  { label: 'Type',     value: 'Markdown document' },
  { label: 'Size',     value: '4.2 KB' },
  { label: 'Modified', value: 'Feb 23, 2026' },
  { label: 'Owner',    value: 'ubuntu' },
  { label: 'Location', value: '~/Documents' },
];

export function DialogNonModal() {
  return (
    <Dialog.Root modal={false}>
      <Dialog.Trigger className="inline-flex items-center justify-center gap-2 rounded-xl text-sm font-medium leading-none transition-colors duration-150 focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 h-9 border border-border bg-card px-4 text-foreground hover:bg-accent">
        <Icons.ExternalLink className="size-4 shrink-0" />
        File details
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Popup className="fixed top-4 right-4 w-72 overflow-hidden rounded-xl border border-border bg-card shadow-xl outline-none transition-all duration-200 data-[ending-style]:translate-x-4 data-[ending-style]:opacity-0 data-[starting-style]:translate-x-4 data-[starting-style]:opacity-0">
          <div className="flex items-center gap-3 border-b border-border px-4 py-3">
            <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-primary/10 text-primary">
              <Icons.Lock className="size-4" />
            </div>
            <Dialog.Title className="flex-1 text-sm font-semibold text-foreground">
              project-notes.md
            </Dialog.Title>
            <Dialog.Close className="flex h-6 w-6 items-center justify-center rounded-md text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring">
              <Icons.X className="size-3.5" />
            </Dialog.Close>
          </div>

          <div className="flex flex-col divide-y divide-border">
            {rows.map(({ label, value }) => (
              <div key={label} className="flex items-center justify-between px-4 py-2.5">
                <span className="text-xs text-muted-foreground">{label}</span>
                <span className="font-mono text-xs text-foreground">{value}</span>
              </div>
            ))}
          </div>

          <Dialog.Description className="border-t border-border px-4 py-3 text-xs leading-relaxed text-muted-foreground">
            Page is still interactive while this panel is open.
          </Dialog.Description>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

DialogBackdrop

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

Documentation: Base UI Dialog

API reference

Root

Groups all parts of the dialog. Doesn’t render its own HTML element.

Root Props:

Prop	Type	Default	Description
defaultOpen	`boolean`	`false`	Whether the dialog is initially open.To render a controlled dialog, use the `open` prop instead.
open	`boolean`	-	Whether the dialog is currently open.
onOpenChange	`((open: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => void)`	-	Event handler called when the dialog is opened or closed.
actionsRef	`RefObject<Dialog.Root.Actions \| null>`	-	A ref to imperative actions.* `unmount`: When specified, the dialog will not be unmounted when closed. Instead, the `unmount` function must be called to unmount the dialog manually. Useful when the dialog's animation is controlled by an external library.
* `close`: Closes the dialog imperatively when called.
defaultTriggerId	`string \| null`	-	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.
disablePointerDismissal	`boolean`	`false`	Determines whether the dialog should close on outside clicks.
handle	`Dialog.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.
modal	`boolean \| 'trap-focus'`	`true`	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. | | onOpenChangeComplete | ((open: boolean) => void) | - | Event handler called after any animations complete when the dialog is opened or closed. | | triggerId | string \| null | - | 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 popover is uncontrolled (i.e. when the open prop is not set). | | children | ReactNode \| PayloadChildRenderFunction<Payload> | - | The content of the dialog. This can be a regular React node or a render function that receives the payload of the active trigger. |

Trigger

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

Trigger Props:

Prop	Type	Default	Description
handle	`Dialog.Handle<Payload>`	-	A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
nativeButton	`boolean`	`true`	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 (e.g. `<div>`).
payload	`Payload`	-	A payload to pass to the dialog when it is opened.
id	`string`	-	ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialogs in controlled mode (with the Dialog.Root `triggerId` prop).
className	`string \| ((state: Dialog.Trigger.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Dialog.Trigger.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Trigger.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Trigger Data Attributes:

Attribute	Type	Description
data-popup-open	-	Present when the corresponding dialog is open.
data-disabled	-	Present when the trigger is disabled.

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.

Portal Props:

Prop	Type	Default	Description
container	`HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null`	-	A parent element to render the portal element into.
className	`string \| ((state: Dialog.Portal.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Dialog.Portal.State) => CSSProperties \| undefined)`	-	-
keepMounted	`boolean`	`false`	Whether to keep the portal mounted in the DOM while the popup is hidden.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Portal.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Backdrop

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

Backdrop Props:

Prop	Type	Default	Description
forceRender	`boolean`	`false`	Whether the backdrop is forced to render even when nested.
className	`string \| ((state: Dialog.Backdrop.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Dialog.Backdrop.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Backdrop.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Backdrop Data Attributes:

Attribute	Type	Description
data-open	-	Present when the dialog is open.
data-closed	-	Present when the dialog is closed.
data-starting-style	-	Present when the dialog is animating in.
data-ending-style	-	Present when the dialog is animating out.

Viewport

A positioning container for the dialog popup that can be made scrollable. Renders a <div> element.

Viewport Props:

Prop	Type	Default	Description
className	`string \| ((state: Dialog.Viewport.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Dialog.Viewport.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Viewport.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Viewport Data Attributes:

Attribute	Type	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 is animating in.
data-ending-style	-	Present when the dialog is animating out.

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

Popup Props:

Prop	Type	Default	Description
initialFocus	`boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)`	-	Determines the element to focus when the dialog is opened.* `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, or false/undefined to do nothing. | | finalFocus | boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null) | - | 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, or false/undefined to do nothing. | | className | string \| ((state: Dialog.Popup.State) => string \| undefined) | - | CSS class applied to the element, or a function that returns a class based on the component’s state. | | style | CSSProperties \| ((state: Dialog.Popup.State) => CSSProperties \| undefined) | - | - | | render | ReactElement \| ((props: HTMLProps, state: Dialog.Popup.State) => ReactElement) | - | Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render. |

Popup Data Attributes:

Attribute	Type	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 is animating in.
data-ending-style	-	Present when the dialog is animating out.

Popup CSS Variables:

Variable	Type	Default	Description
--nested-dialogs	`number`	-	Indicates how many dialogs are nested within.

Title

A heading that labels the dialog. Renders an <h2> element.

Title Props:

Prop	Type	Default	Description
className	`string \| ((state: Dialog.Title.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Dialog.Title.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Title.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Description

A paragraph with additional information about the dialog. Renders a <p> element.

Description Props:

Prop	Type	Default	Description
className	`string \| ((state: Dialog.Description.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Dialog.Description.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Description.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Close

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

Close Props:

Prop	Type	Default	Description
nativeButton	`boolean`	`true`	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 (e.g. `<div>`).
className	`string \| ((state: Dialog.Close.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Dialog.Close.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Close.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Close Data Attributes:

Attribute	Type	Description
data-disabled	-	Present when the button is disabled.

Dialog

On this page