useDialog

Hook that manages dialog open/close state, focus trapping, dragging, scroll lock, and z-index layering.

basic-demo

Usage#

import { useMotion } from '@primereact/core/motion';
import { useDialog } from '@primereact/headless/dialog';
import { usePortal } from '@primereact/headless/portal';
import * as React from 'react';
import { createPortal } from 'react-dom';
 
const { rootProps, triggerProps, backdropProps, positionerProps, popupProps, closeProps, headerProps, contentProps, maximizableProps, state } = useDialog();
const portal = usePortal();
 
return (
    <div {...rootProps}>
        <button {...triggerProps}></button>
        {portal.state.mounted &&
            createPortal(
                <>
                    <div {...backdropProps} />
                    <div {...positionerProps}>
                        <div {...popupProps}>
                            <div {...headerProps}>
                                <button {...maximizableProps}></button>
                                <button {...closeProps}></button>
                            </div>
                            <div {...contentProps}></div>
                        </div>
                    </div>
                </>,
                document.body
            )}
    </div>
);

useDialog manages open/close state, focus trapping, dragging, scroll locking, and z-index layering — see Primitive for a component-based API.

Features#

Returns spread-ready prop objects: rootProps, triggerProps, backdropProps, positionerProps, popupProps, closeProps, headerProps, contentProps, maximizableProps
Combine with usePortal and createPortal for SSR-safe portal rendering
Combine with useMotion for animated open/close transitions with automatic focus management
Automatic focus trap: first focusable element receives focus on open, focus returns to trigger on close
close() and toggleMaximized() imperative methods for programmatic control
state.open and state.maximized for conditional rendering

Behavior#

Default Open#

Set defaultOpen for initial visibility in uncontrolled mode.

const dialog = useDialog({ defaultOpen: true });

Controlled#

Pass open and onOpenChange for controlled usage.

const [isOpen, setIsOpen] = React.useState(false);
 
const dialog = useDialog({
    open: isOpen,
    onOpenChange: (e) => setIsOpen(e.value)
});

Dismissable#

Set dismissable to close the dialog when clicking the backdrop. Defaults to true.

const dialog = useDialog({ dismissable: true });

Block Scroll#

Set blockScroll to prevent body scrolling while the dialog is open.

const dialog = useDialog({ blockScroll: true });

Draggable#

Enable drag support via the draggable prop. Dragging is initiated via headerProps.onMouseDown. Disabled by default.

const dialog = useDialog({ draggable: true });

Position#

Use position to place the dialog at a specific viewport location. Defaults to center.

const dialog = useDialog({ position: 'top' });

Available values: center, top, bottom, left, right, topleft, topright, bottomleft, bottomright.

Scroll Behavior#

Use scrollBehavior to control how long content scrolls. When set to inside (default), the dialog content area scrolls. When set to outside, the positioner scrolls allowing the entire dialog to move as a single unit.

const dialog = useDialog({ scrollBehavior: 'outside' });

Full Screen#

Set fullScreen to open the dialog in maximized mode.

const dialog = useDialog({ fullScreen: true });

Z-Index Management#

Use baseZIndex and autoZIndex to control layering. When autoZIndex is true, the dialog automatically manages its z-index relative to other overlays.

const dialog = useDialog({ baseZIndex: 1000, autoZIndex: true });

Using `close` and `toggleMaximized`#

The hook exposes imperative methods for programmatic control.

const dialog = useDialog();
 
// Programmatically close the dialog
dialog.close();
 
// Toggle maximized state
dialog.toggleMaximized();

Custom Styling with Data Attributes#

positionerProps includes data-position and data-scroll-behavior attributes. rootProps and popupProps include data-open, data-closed, and data-maximized attributes for CSS-based styling.

[data-scope='dialog'][data-part='positioner'] {
    position: fixed;
    inset: 0;
    display: flex;
    align-items: center;
    justify-content: center;
}
 
[data-scope='dialog'][data-part='positioner'][data-position='top'] {
    align-items: flex-start;
}
 
[data-scope='dialog'][data-part='positioner'][data-scroll-behavior='outside'] {
    overflow: auto;
    align-items: flex-start;
}
 
[data-scope='dialog'][data-part='popup'][data-maximized] {
    width: 100vw;
    height: 100vh;
}

maximizableProps includes data-maximized and data-minimized attributes for toggling icon visibility.

[data-scope='dialog'][data-part='maximizable'][data-maximized] .maximize-icon {
    display: none;
}
[data-scope='dialog'][data-part='maximizable'][data-minimized] .minimize-icon {
    display: none;
}

API#

useDialog#

Name	Type	Default
`open`	`boolean`	—
Specifies the visibility of the dialog.
`defaultOpen`	`boolean`	—
Specifies the default visibility of the dialog.
`draggable`	`boolean`	`true`
Enables dragging to change the position using header.
`keepInViewport`	`boolean`	`true`
Keeps dialog in the viewport.
`minX`	`number`	`0`
Minimum value for the left coordinate of dialog in dragging.
`minY`	`number`	`0`
Minimum value for the top coordinate of dialog in dragging.
`trapped`	`boolean`	`true`
When enabled, focus is trapped within the dialog (modal behavior).
`dismissable`	`boolean`	`false`
Specifies if clicking the modal background should hide the dialog.
`closeOnEscape`	`boolean`	`true`
Specifies if pressing escape key should hide the dialog.
`blockScroll`	`boolean`	`false`
Whether background scroll should be blocked when dialog is visible.
`baseZIndex`	`number`	`0`
Base zIndex value to use in layering.
`autoZIndex`	`boolean`	`true`
Whether to automatically manage layering.
`appendTo`	`"body"` \| `HTMLElement` \| `"self"`	`body`
A valid query selector or an HTMLElement to specify where the dialog gets attached.
`position`	`"center"` \| `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"topleft"` \| `"topright"` \| `"bottomleft"` \| `"bottomright"`	`center`
Position of the dialog.
`fullScreen`	`boolean`	`false`
Whether the dialog should open in full screen (maximized) mode.
`onOpenChange`	`(event: useDialogChangeEvent) => void`	—
Callback function that is called when the trigger is clicked.

Accessibility#

See Dialog Primitive for WAI-ARIA compliance details and keyboard support.