Dialog

Renders a dialog similar to the native dialog element that's rendered in a portal by default.

The dialog can be either modal or non-modal. The visibility state can be controlled with the open and onClose props.

Code examples

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

<button onClick={() => setOpen(true)}>Open dialog</button>
<Dialog open={open} onClose={() => setOpen(false)}>
  Dialog
</Dialog>
const [open, setOpen] = useState(false);

<button onClick={() => setOpen(true)}>Open dialog</button>
<Dialog open={open} onClose={() => setOpen(false)}>
  Dialog
</Dialog>

Optional Props

`accessibleWhenDisabled`

boolean | undefined
boolean | undefined

Indicates whether the element should be focusable even when it is disabled.

This is important when discoverability is a concern. For example:

A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard. It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar.

Learn more on Focusability of disabled controls⁠.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

`alwaysVisible`

boolean | undefined = false
boolean | undefined = false

Determines whether the content element should remain visible even when the open state is false. If this prop is set to true, the hidden prop and the display: none style will not be applied, unless explicitly set otherwise.

This prop is particularly useful when using third-party animation libraries such as Framer Motion or React Spring, where the element needs to be visible for exit animations to work.

Live examples

Dialog with Framer MotionUsing Framer Motion to add initial and exit animations to a modal Dialog and its backdrop element.

Menu with Framer MotionAbstracting Menu into a reusable dropdown menu component that uses Framer Motion to create smooth initial and exit animations.

Tooltip with Framer MotionAbstracting Tooltip into a reusable custom component that uses Framer Motion to create smooth initial and exit animations.

Dialog with details & summaryCombining Dialog with the native details element in React so users can interact with it before JavaScript finishes loading.

`autoFocus`

boolean | undefined = false
boolean | undefined = false

Automatically focuses the element upon mounting, similar to the native autoFocus prop. This addresses an issue where the element with the native autoFocus attribute might receive focus before React effects are executed.

The autoFocus prop can also be used with Focusable elements within a Dialog component, establishing the initial focus as the dialog opens.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

Warning on Dialog hidePreventing users from accidentally closing a modal Dialog component with unsaved changes by displaying a nested confirmation dialog.

Dialog with React RouterUsing React Router to create a modal Dialog that's controlled by the browser history.

Nested DialogRendering a modal Dialog to confirm an action inside another modal dialog using React.

`autoFocusOnHide`

BooleanOrCallback<HTMLElement | null> | undefined = true
BooleanOrCallback<HTMLElement | null> | undefined = true

Determines whether an element outside of the dialog will be focused when the dialog is hidden if another element hasn't been focused in the action of hiding the dialog (for example, by clicking or tabbing into another tabbable element outside of the dialog).

By default, this is usually the disclosure element. The finalFocus prop can be used to define a different element to be focused.

Live examples

Dialog with Next.js App RouterUsing Next.js Parallel Routes to create an accessible modal Dialog that is rendered on the server and controlled by the URL, with built-in focus management.

Sliding MenuRendering nested Menu components to create submenus that slide in and out using CSS Scroll Snap.

`autoFocusOnShow`

BooleanOrCallback<HTMLElement | null> | undefined = true
BooleanOrCallback<HTMLElement | null> | undefined = true

Determines whether an element inside the dialog will receive focus when the dialog is shown. By default, this is usually the first tabbable element in the dialog or the dialog itself. The initialFocus prop can be used to set a different element to receive focus.

Live examples

Warning on Dialog hidePreventing users from accidentally closing a modal Dialog component with unsaved changes by displaying a nested confirmation dialog.

Sliding MenuRendering nested Menu components to create submenus that slide in and out using CSS Scroll Snap.

Selection PopoverShowing an inline Popover when a text is selected. This example uses the getAnchorRect prop to position the flyout relative to the selected text.

`backdrop`

boolean | React.ReactElement<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | ... 2 more ... | undefined; }, string | React.JSXElementConstructor<...>> | React.ElementType<...> | undefined
boolean | React.ReactElement<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | ... 2 more ... | undefined; }, string | React.JSXElementConstructor<...>> | React.ElementType<...> | undefined

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.

Live examples

Animated DialogAnimating a modal Dialog and its backdrop element using CSS. The component waits for the transition to finish before completely hiding the dialog or removing it from the React tree.

Dialog with scrollable backdropRendering a modal Dialog component inside a scrollable backdrop container for dialogs that are taller than the viewport.

Dialog with Framer MotionUsing Framer Motion to add initial and exit animations to a modal Dialog and its backdrop element.

Dialog with MenuShowing a nested dropdown Menu component inside a modal Dialog using React.

Nested DialogRendering a modal Dialog to confirm an action inside another modal dialog using React.

Dialog with Next.js App RouterUsing Next.js Parallel Routes to create an accessible modal Dialog that is rendered on the server and controlled by the URL, with built-in focus management.

Code examples

<Dialog backdrop={<div className="backdrop" />} />
<Dialog backdrop={<div className="backdrop" />} />

`disabled`

boolean | undefined = false
boolean | undefined = false

Determines if the element is disabled. This sets the aria-disabled attribute accordingly, enabling support for all elements, including those that don't support the native disabled attribute.

This feature can be combined with the accessibleWhenDisabled prop to make disabled elements still accessible via keyboard.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

SubmenuRendering nested Menu components to create a dropdown menu with submenus that open when hovering over the parent menu item.

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Context menuShowing Menu when right-clicking on an element using the getAnchorRect prop to determine the position of the popover.

`finalFocus`

HTMLElement | React.RefObject<HTMLElement> | null | undefined
HTMLElement | React.RefObject<HTMLElement> | null | undefined

Determines the element that will receive focus once the dialog is closed, provided that no other element has been focused while the dialog was being hidden (e.g., by clicking or tabbing into another tabbable element outside of the dialog).

If autoFocusOnHide is set to false, this prop will have no effect.
If left unset, the element that was focused before the dialog was opened will be focused again.

`focusable`

boolean | undefined = true
boolean | undefined = true

Determines if Focusable features should be active on non-native focusable elements.

Note: This prop only turns off the additional features provided by the Focusable component. Non-native focusable elements will lose their focusability entirely. However, native focusable elements will retain their inherent focusability, but without added features such as improved autoFocus, accessibleWhenDisabled, onFocusVisible, etc.

`getPersistentElements`

(() => Iterable<Element>) | undefined
(() => Iterable<Element>) | undefined

When a dialog is open, the elements outside of it are disabled to prevent interaction if the dialog is modal. For non-modal dialogs, interacting with elements outside the dialog prompts it to close.

This function allows you to return an iterable collection of elements that will be considered as part of the dialog, thus excluding them from this behavior.

Note: The elements returned by this function must exist in the DOM when the dialog opens.

Live examples

Dialog with React-ToastifyShowing notification toasts using libraries like react-toastify and react-hot-toast while keeping a modal Dialog open with the getPersistentElements prop.

`hideOnEscape`

BooleanOrCallback<KeyboardEvent | React.KeyboardEvent<Element>> | undefined = true
BooleanOrCallback<KeyboardEvent | React.KeyboardEvent<Element>> | undefined = true

Determines if the dialog will hide when the user presses the Escape key.

This prop can be either a boolean or a function that accepts an event as an argument and returns a boolean. The event object represents the keydown event that initiated the hide action, which could be either a native keyboard event or a React synthetic event.

Note: When placing Ariakit dialogs inside third-party dialogs, using event.stopPropagation() within this function will stop the event from reaching the third-party dialog, closing only the Ariakit dialog.

`hideOnInteractOutside`

BooleanOrCallback<Event | React.SyntheticEvent<Element, Event>> | undefined = true
BooleanOrCallback<Event | React.SyntheticEvent<Element, Event>> | undefined = 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.

Live examples

Selection PopoverShowing an inline Popover when a text is selected. This example uses the getAnchorRect prop to position the flyout relative to the selected text.

`initialFocus`

HTMLElement | React.RefObject<HTMLElement> | null | undefined
HTMLElement | React.RefObject<HTMLElement> | null | undefined

Specifies the element that will receive focus when the dialog is first opened. It can be an HTMLElement or a React.RefObject with an HTMLElement.

If autoFocusOnShow is set to false, this prop will have no effect. If left unset, the dialog will attempt to determine the initial focus element in the following order:

1
A Focusable element with an autoFocus prop.
2
The first tabbable element inside the dialog.
3
The first focusable element inside the dialog.
4
The dialog element itself.

`modal`

boolean | undefined = true
boolean | undefined = true

Determines whether the dialog is modal. Modal dialogs have distinct states and behaviors:

The portal and preventBodyScroll props are set to true. They can still be manually set to false.
When using the Heading or DialogHeading components within the dialog, their level will be reset so they start with h1.
A visually hidden dismiss button will be rendered if the DialogDismiss component hasn't been used. This allows screen reader users to close the dialog.
When the dialog is open, element tree outside it will be inert.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Dialog with details & summaryCombining Dialog with the native details element in React so users can interact with it before JavaScript finishes loading.

Form with SelectCombining Form and Select to create an accessible custom select widget that works with the browser's built-in validation and native form submission.

Context menuShowing Menu when right-clicking on an element using the getAnchorRect prop to determine the position of the popover.

Responsive PopoverOverwriting the default Popover positioning styles on small screens using the updatePosition prop.

`onClose`

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

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.

Live examples

Dialog with scrollable backdropRendering a modal Dialog component inside a scrollable backdrop container for dialogs that are taller than the viewport.

Dialog with details & summaryCombining Dialog with the native details element in React so users can interact with it before JavaScript finishes loading.

Warning on Dialog hidePreventing users from accidentally closing a modal Dialog component with unsaved changes by displaying a nested confirmation dialog.

Dialog with MenuShowing a nested dropdown Menu component inside a modal Dialog using React.

`onFocusVisible`

BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void> | undefined
BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void> | undefined

Custom event handler invoked when the element gains focus through keyboard interaction or a key press occurs while the element is in focus. This is the programmatic equivalent of the data-focus-visible attribute.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Custom CheckboxRendering a visually hidden Checkbox using the VisuallyHidden component to show a custom checkbox presentation in React.

`open`

boolean | undefined
boolean | undefined

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

Live examples

Dialog with scrollable backdropRendering a modal Dialog component inside a scrollable backdrop container for dialogs that are taller than the viewport.

Dialog with details & summaryCombining Dialog with the native details element in React so users can interact with it before JavaScript finishes loading.

Warning on Dialog hidePreventing users from accidentally closing a modal Dialog component with unsaved changes by displaying a nested confirmation dialog.

Dialog with MenuShowing a nested dropdown Menu component inside a modal Dialog using React.

`portal`

boolean | undefined = true
boolean | undefined = true

Determines whether the element should be rendered as a React Portal.

Live examples

Combobox with integrated filterFiltering options in a Combobox component through an abstracted implementation using React.useDeferredValue, resulting in a simple higher-level API.

Dialog with MenuShowing a nested dropdown Menu component inside a modal Dialog using React.

Hovercard with keyboard supportUsing the HovercardDisclosure component to render a Hovercard that can be opened with the keyboard.

MenubarRender a visually persistent menu similar to those found near the top of the window in desktop apps. This component is based on the WAI-ARIA Menubar Pattern.

Standalone PopoverAbstracting the Popover component so that it can be used without PopoverDisclosure or PopoverAnchor. This example uses the getAnchorRect prop to determine the position of the popup.

Animated SelectAnimating Select using CSS transitions in React. The component waits for the transition to finish before completely hiding the popover.

`portalElement`

HTMLElement | ((element: HTMLElement) => HTMLElement | null) | null | undefined
HTMLElement | ((element: HTMLElement) => HTMLElement | null) | null | undefined

An HTML element or a memoized callback function that returns an HTML element to be used as the portal element. By default, the portal element will be a div element appended to the document.body.

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Code examples

const [portal, setPortal] = useState(null);

<Portal portalElement={portal} />
<div ref={setPortal} />
const [portal, setPortal] = useState(null);

<Portal portalElement={portal} />
<div ref={setPortal} />

const getPortalElement = useCallback(() => {
  const div = document.createElement("div");
  const portalRoot = document.getElementById("portal-root");
  portalRoot.appendChild(div);
  return div;
}, []);

<Portal portalElement={getPortalElement} />
const getPortalElement = useCallback(() => {
  const div = document.createElement("div");
  const portalRoot = document.getElementById("portal-root");
  portalRoot.appendChild(div);
  return div;
}, []);

<Portal portalElement={getPortalElement} />

`portalRef`

React.RefCallback<HTMLElement> | React.MutableRefObject<HTMLElement | null> | undefined
React.RefCallback<HTMLElement> | React.MutableRefObject<HTMLElement | null> | undefined

portalRef is similar to ref but is scoped to the portal node. It's useful when you need to be informed when the portal element is appended to the DOM or removed from the DOM.

Live examples

Form with SelectCombining Form and Select to create an accessible custom select widget that works with the browser's built-in validation and native form submission.

Code examples

const [portalElement, setPortalElement] = useState(null);

<Portal portalRef={setPortalElement} />
const [portalElement, setPortalElement] = useState(null);

<Portal portalRef={setPortalElement} />

`preserveTabOrder`

boolean | undefined = false
boolean | undefined = false

When enabled, preserveTabOrder will keep the DOM element's tab order the same as the order in which the underlying Portal component was mounted in the React tree.

If the preserveTabOrderAnchor prop is provided, the tab order will be preserved relative to that element.

`preserveTabOrderAnchor`

Element | null | undefined
Element | null | undefined

An anchor element for maintaining the tab order when preserveTabOrder prop is enabled. The tab order will be kept relative to this element.

By default, the tab order is kept relative to the original location in the React tree where the underlying Portal component was mounted.

Code examples

const [anchor, setAnchor] = useState(null);

<button ref={setAnchor}>Order 0</button>
<button>Order 2</button>

// Rendered at the end of the document.
<Portal>
  <button>Order 5</button>
</Portal>

// Rendered at the end of the document, but the tab order is preserved.
<Portal preserveTabOrder>
  <button>Order 3</button>
</Portal>

// Rendered at the end of the document, but the tab order is preserved
// relative to the anchor element.
<Portal preserveTabOrder preserveTabOrderAnchor={anchor}>
  <button>Order 1</button>
</Portal>

<button>Order 4</button>
const [anchor, setAnchor] = useState(null);

<button ref={setAnchor}>Order 0</button>
<button>Order 2</button>

// Rendered at the end of the document.
<Portal>
  <button>Order 5</button>
</Portal>

// Rendered at the end of the document, but the tab order is preserved.
<Portal preserveTabOrder>
  <button>Order 3</button>
</Portal>

// Rendered at the end of the document, but the tab order is preserved
// relative to the anchor element.
<Portal preserveTabOrder preserveTabOrderAnchor={anchor}>
  <button>Order 1</button>
</Portal>

<button>Order 4</button>

`preventBodyScroll`

boolean | undefined
boolean | undefined

Determines whether the body scrolling will be prevented when the dialog is shown. This is automatically set to true when the dialog is modal. You can disable this prop if you want to implement your own logic.

`render`

RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>> | undefined
RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>> | undefined

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

`store`

DialogStore | undefined
DialogStore | undefined

Object returned by the useDialogStore hook. If not provided, the closest DialogProvider component's context will be used. Otherwise, an internal store will be created.

`unmountOnHide`

boolean | undefined = false
boolean | undefined = false

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

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Combobox with integrated filterFiltering options in a Combobox component through an abstracted implementation using React.useDeferredValue, resulting in a simple higher-level API.

Textarea with inline ComboboxRendering Combobox as a textarea element to create an accessible multiline textbox in React. Inserting specific characters triggers a popup with dynamic suggestions.

Standalone PopoverAbstracting the Popover component so that it can be used without PopoverDisclosure or PopoverAnchor. This example uses the getAnchorRect prop to determine the position of the popup.

Animated SelectAnimating Select using CSS transitions in React. The component waits for the transition to finish before completely hiding the popover.

Multi-SelectAllowing the Select component to select multiple values by passing an array to the defaultValue prop on the SelectProvider component.

Dialog

Live examples

Live examples

Live examples

Live examples

Live examples

Live examples

Code examples

Live examples

Live examples

Live examples

Live examples

Live examples

Live examples

Live examples

Live examples

Live examples

Code examples

Live examples

Code examples

Code examples

Live examples

Stay tuned