unstable_Dialog API

Import

import { unstable_Dialog as Dialog } from "@stratakit/structures";
// OR
import * as Dialog from "@stratakit/structures/unstable_Dialog";

Dialog.Root

Base element: <div>

A modal dialog component used to display content in a window overlay. Must include Dialog.Header and Dialog.Content as direct descendants. Additionally, Dialog.Footer can be optionally used as a direct descendant.

Example:

const [open, setOpen] = useState(false);

<Dialog.Root modal={true} open={open} onClose={() => setOpen(false)}>
  <Dialog.Heading>Heading</Dialog.Heading>
  <Dialog.Content>Content</Dialog.Content>
  <Dialog.Footer>
    <Dialog.ActionList
      actions={[
        <Button key="ok" onClick={() => setOpen(false)}>Ok</Button>,
      ]}
    />

  </Dialog.Footer>
</Dialog.Root>

modal

Type: true (required)

Determines whether the dialog is modal. Currently, only modal dialogs are supported.

backdrop

Type: boolean | ReactElement<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, string | JSXElementConstructor<any>> | ElementType<...> | undefined (optional)

Determines whether there will be a backdrop behind the dialog. On modal dialogs, this is true by default. Besides a boolean, this prop can also be a React component or JSX element that will be rendered as the backdrop.

Note: If a custom component is used, it must accept ref and spread all props to its underlying DOM element, the same way a native element would.

hideOnInteractOutside

Type: BooleanOrCallback<Event | SyntheticEvent<Element, Event>> | undefined (optional)

Default: true

Determines if the dialog should hide when the user clicks or focuses on an element outside the dialog.

This prop can be either a boolean or a function that takes an event as an argument and returns a boolean. The event object represents the event that triggered the action, which could be a native event or a React synthetic event of various types.

onClose

Type: ((event: Event) => void) | undefined (optional)

This is an event handler prop triggered when the dialog’s close event is dispatched. The close event is similar to the native dialog close event. The only difference is that this event can be canceled with event.preventDefault(), which will prevent the dialog from hiding.

It’s important to note that this event only fires when the dialog store’s open state is set to false. If the controlled open prop value changes, or if the dialog’s visibility is altered in any other way (such as unmounting the dialog without adjusting the open state), this event won’t be triggered.

open

Type: boolean | undefined (optional)

Controls the open state of the dialog. This is similar to the open attribute on native dialog elements.

unmountOnHide

Type: boolean | undefined (optional)

Default: true

When set to true, the content element will be unmounted and removed from the DOM when it’s hidden.

Additional props

• render

Dialog.Header

Base element: <div>

The header of a dialog. Should be used as a child of Dialog.Root. Must include Dialog.Heading as a direct descendant. Additionally, Dialog.CloseButton can be optionally used as a direct descendant.

Example:

<Dialog.Header>
  <Dialog.Heading>Heading</Dialog.Heading>
  <Dialog.CloseButton />
</Dialog.Header>

Use render prop when only a heading is displayed in a header.

<Dialog.Header render={<Dialog.Heading />}>Heading</Dialog.Header>

Additional props

• render

Dialog.Heading

Base element: <h1>

The heading of a dialog. Should be used as a child of Dialog.DialogHeader.

Example:

<Dialog.Heading>Heading</Dialog.Heading>

Additional props

• render

Dialog.CloseButton

Base element: <button>

A button that closes the dialog. Displayed as an icon button in the top-right corner of the dialog. Should be used as a child of Dialog.DialogHeader.

Example:

<Dialog.CloseButton />

label

Type: string | undefined (optional)

Default: "Dismiss"

Label for the close button.

Additional props

• render
• autoFocus
• disabled
• accessibleWhenDisabled

Dialog.Content

Base element: <div>

The content of a dialog. Should be used as a child of Dialog.Root.

Example:

<Dialog.Content>Content</Dialog.Content>

Additional props

• render

Dialog.Footer

Base element: <div>

The footer section of a dialog, typically used to display action buttons at the bottom of the dialog. Should be used as a child of Dialog.Root. Use Dialog.ActionList as a direct descendant to display a list of actions.

Example:

<Dialog.Footer>
  <Dialog.ActionList
    actions={[
      <Button key="cancel" onClick={() => setOpen(false)}>Cancel</Button>,
      <Button key="ok" tone="accent" onClick={() => setOpen(false)}>Ok</Button>,
    ]}
  />
</Dialog.Footer>

Additional props

• render

Dialog.ActionList

Base element: <div>

A container for action buttons in a dialog. Should be used as a child of Dialog.Footer.

Example:

<Dialog.ActionList
  actions={[
    <Button key="cancel" onClick={() => setOpen(false)}>Cancel</Button>,
    <Button key="ok" tone="accent" onClick={() => setOpen(false)}>Ok</Button>,
  ]}
/>

actions

Type: ReactNode[] | undefined (optional)

The actions available for the dialog. Must be a list of Button components.

Additional props

• render

Dialog.Backdrop

Base element: <div>

The backdrop of a dialog. Should be passed into the backdrop prop of Dialog.Root.

Example:

<Dialog.Root modal={true} backdrop={<Dialog.Backdrop />} />

Additional props

• render