Dialog

A window overlaid on either the primary window or another dialog window.

0.2.3

Features Section titled Features

Supports modal and non-modal modes
Customizable focus management
Waits for pending animations before removing the dialog from the DOM
Pressing the escape key and interacting outside closes the dialog
Supports nested dialogs

Installation Section titled Installation

npm install @corvu/dialog

The dialog is also included in the main corvu package under corvu/dialog.

Usage Section titled Usage

import Dialog from '@corvu/dialog' // 'corvu/dialog'
// or
// import { Root, Trigger, ... } from '@corvu/dialog'

Anatomy Section titled Anatomy

<Dialog>
<Dialog.Trigger />
<Dialog.Portal>
  <Dialog.Overlay />
  <Dialog.Content>
    <Dialog.Close />
    <Dialog.Label />
    <Dialog.Description />
  </Dialog.Content>
</Dialog.Portal>
</Dialog>

Scrolling Section titled Scrolling

By default, corvu prevents scrolling of elements outside of the dialog content while the dialog open. It will also add additional padding to the body to prevent the page from jumping when the scrollbar disappears. There is also a CSS variable called --scrollbar-width which is present when the scrollbar is hidden. You can use this to prevent any fixed element from jumping:

<header
class="fixed top-0 inset-x-0 z-50"
style={{
  'padding-right': 'var(--scrollbar-width, 0)',
}}
>
Header
</header>

Nested dialogs Section titled Nested dialogs

Feel free to nest dialogs however you want. corvu is aware of nested dialogs and only dismisses the top-most dialog when you press the escape key or click outside the dialog.

Persistent content Section titled Persistent content

To persist the content of the dialog even when it’s unmounted, you can use corvu’s createPersistent utility. It will cache the content when the dialog is opened for the first time and preserve its state and HTML elements.

const PersistedDialogContent = () => {
const persistedContent = createPersistent(() => {
  return <input />
})

return (
<Dialog>
    <Dialog.Trigger>
      Open
    </Dialog.Trigger>
    <Dialog.Portal>
      <Dialog.Content>
        {persistedContent()}
      </Dialog.Content>
    </Dialog.Portal>
  </Dialog>
)
}

Give it a try! 🐦‍⬛

Accessibility Section titled Accessibility

Adheres to the Dialog WAI-ARIA design pattern and Alert Dialog WAI-ARIA design pattern.

API reference Section titled API reference

<Root />

Component

Context wrapper for the dialog. Is required for every dialog you create.

Props

Property	Default	Type/Description
role	`'dialog'`	'dialog' \| 'alertdialog' The `role` attribute of the dialog element.
open	-	boolean Whether the dialog is open.
onOpenChange	-	(open: boolean) => void Callback fired when the open state changes.
initialOpen	`false`	boolean Whether the dialog is open initially.
modal	`true`	boolean Whether the dialog should be rendered as a modal.
closeOnEscapeKeyDown	`true`	boolean Whether the dialog should close when the user presses the `Escape` key.
onEscapeKeyDown	-	(event: KeyboardEvent) => void Callback fired when the user presses the `Escape` key. Can be prevented by calling `event.preventDefault`.
closeOnOutsideFocus	`true` if `trapFocus` is `true`, `false` otherwise	boolean Whether the dialog should be closed if a focus event happens outside the bounds of .
closeOnOutsidePointer	`true` if `modal` is `true`, `false` otherwise	boolean Whether the dialog should be closed if the user interacts outside the bounds of .
closeOnOutsidePointerStrategy	`'pointerup'`	'pointerdown' \| 'pointerup' Whether `closeOnOutsidePointer` should be triggered on `pointerdown` or `pointerup`.
onOutsideFocus	-	(event: CustomEvent) => void Callback fired when a focus event happens outside the bounds of . Can only happen if `trapFocus` is set to `false` and can be prevented by calling `event.preventDefault`.
onOutsidePointer	-	(event: PointerEvent) => void Callback fired when the user interacts outside the bounds of . Can be prevented by calling `event.preventDefault`.
noOutsidePointerEvents	`true` if `modal` is `true`, `false` otherwise	boolean Whether pointer events outside of should be disabled.
preventScroll	`true` if `modal` is `true`, `false` otherwise	boolean Whether scroll outside of the dialog should be prevented.
hideScrollbar	`true`	boolean Whether the scrollbar of the element should be hidden. Only applies if `preventScroll` is `true`.
preventScrollbarShift	`true`	boolean Whether padding should be added to the element to avoid layout shift.
preventScrollbarShiftMode	`'padding'`	'padding' \| 'margin' Whether padding or margin should be used to avoid layout shift.
restoreScrollPosition	`true`	boolean Whether to restore the scroll position with `window.scrollTo` to avoid possible layout shift after closing the dialog.
allowPinchZoom	`true`	boolean Whether the dialog should allow pinch zoom while scroll is disabled.
trapFocus	`true`	boolean Whether the dialog should trap focus.
restoreFocus	`true`	boolean Whether the dialog should restore focus to the previous active element when it closes.
initialFocusEl	-	HTMLElement The element to receive focus when the dialog opens.
onInitialFocus	-	(event: Event) => void Callback fired when focus moves into the dialog. Can be prevented by calling `event.preventDefault`.
finalFocusEl	-	HTMLElement The element to receive focus when the dialog closes.
onFinalFocus	-	(event: Event) => void Callback fired when focus moves out of the dialog. Can be prevented by calling `event.preventDefault`.
dialogId	`createUniqueId()`	string The `id` attribute of the dialog element.
labelId	`createUniqueId()`	string The `id` attribute of the dialog label element.
descriptionId	`createUniqueId()`	string The `id` attribute of the dialog description element.
contextId	-	string The `id` of the dialog context. Useful if you have nested dialogs and want to create components that belong to a dialog higher up in the tree.

<Trigger />

Component

Button that changes the open state of the dialog when clicked.

Props

Property	Default	Type/Description
as	`button`	ValidComponent Component to render the dynamic component as.
contextId	-	string The `id` of the dialog context to use.

Data attributes

Data attributes present on <Trigger /> components.

Property	Description
data-corvu-dialog-trigger	Present on every dialog trigger element.
data-open	Present when the dialog is open.
data-closed	Present when the dialog is closed.

<Portal />

Component

Portals its children at the end of the body element to ensure that the dialog always rendered on top.

Props

Property	Default	Type/Description
forceMount	`false`	boolean Whether the dialog portal should be forced to render. Useful when using third-party animation libraries.
contextId	-	string The `id` of the dialog context to use.

<Overlay />

Component

Component which can be used to create a faded background. Can be animated.

Props

Property	Default	Type/Description
as	`div`	ValidComponent Component to render the dynamic component as.
forceMount	`false`	boolean Whether the dialog overlay should be forced to render. Useful when using third-party animation libraries.
contextId	-	string The `id` of the dialog context to use.

Data attributes

Data attributes present on <Overlay /> components.

Property	Description
data-corvu-dialog-overlay	Present on every dialog overlay element.
data-open	Present when the dialog is open.
data-closed	Present when the dialog is closed.

<Content />

Component

Content of the dialog. Can be animated.

Props

Property	Default	Type/Description
as	`div`	ValidComponent Component to render the dynamic component as.
forceMount	`false`	boolean Whether the dialog content should be forced to render. Useful when using third-party animation libraries.
contextId	-	string The `id` of the dialog context to use.

Data attributes

Data attributes present on <Content /> components.

Property	Description
data-corvu-dialog-content	Present on every dialog content element.
data-open	Present when the dialog is open.
data-closed	Present when the dialog is closed.

<Close />

Component

Close button that changes the open state to false when clicked.

Props

Property	Default	Type/Description
as	`button`	ValidComponent Component to render the dynamic component as.
contextId	-	string The `id` of the dialog context to use.

Data attributes

Data attributes present on <Close /> components.

Property	Description
data-corvu-dialog-close	Present on every dialog close element.

<Label />

Component

Label element to announce the dialog to accessibility tools.

Props

Property	Default	Type/Description
as	`h2`	ValidComponent Component to render the dynamic component as.
contextId	-	string The `id` of the dialog context to use.

Data attributes

Data attributes present on <Label /> components.

Property	Description
data-corvu-dialog-label	Present on every dialog label element.

<Description />

Component

Description element to announce the dialog to accessibility tools.

Props

Property	Default	Type/Description
as	`p`	ValidComponent Component to render the dynamic component as.
contextId	-	string The `id` of the dialog context to use.

Data attributes

Data attributes present on <Description /> components.

Property	Description
data-corvu-dialog-description	Present on every dialog description element.

useContext

Context

Context which exposes various properties to interact with the dialog. Optionally provide a contextId to access a keyed context.

Returns

Property	Type/Description
role	Accessor<'dialog' \| 'alertdialog'> The `role` attribute of the dialog element.
open	Accessor<boolean> Whether the dialog is open.
setOpen	Setter<boolean> Change the open state of the dialog.
modal	Accessor<boolean> Whether the dialog should be rendered as a modal.
closeOnEscapeKeyDown	Accessor<boolean> Whether the dialog should close when the user presses the `Escape` key.
closeOnOutsideFocus	Accessor<boolean> Whether the dialog should be closed if a focus event happens outside the bounds of .
closeOnOutsidePointer	Accessor<boolean> Whether the dialog should be closed if the user interacts outside the bounds of .
closeOnOutsidePointerStrategy	Accessor<'pointerdown' \| 'pointerup'> Whether `closeOnOutsidePointer` should be triggered on `pointerdown` or `pointerup`.
noOutsidePointerEvents	Accessor<boolean> Whether pointer events outside of should be disabled.
preventScroll	Accessor<boolean> Whether scroll outside of the dialog should be prevented.
hideScrollbar	Accessor<boolean> Whether the scrollbar of the element should be hidden.
preventScrollbarShift	Accessor<boolean> Whether padding should be added to the element to avoid layout shift.
preventScrollbarShiftMode	Accessor<'padding' \| 'margin'> Whether padding or margin should be used to avoid layout shift.
restoreScrollPosition	Accessor<boolean> Whether to restore the scroll position with `window.scrollTo` to avoid possible layout shift after closing the dialog.
allowPinchZoom	Accessor<boolean> Whether the dialog should allow pinch zoom while scroll is disabled.
trapFocus	Accessor<boolean> Whether the dialog should trap focus.
restoreFocus	Accessor<boolean> Whether the dialog should restore focus to the previous active element when it closes.
initialFocusEl	Accessor<HTMLElement \| undefined> The element to receive focus when the dialog opens.
finalFocusEl	Accessor<HTMLElement \| undefined> The element to receive focus when the dialog closes.
contentPresent	Accessor<boolean> Whether the dialog content is present. This differes from `open` as it tracks pending animations.
contentRef	Accessor<HTMLElement \| null> The ref of the dialog content.
overlayPresent	Accessor<boolean> Whether the dialog overlay is present. This differes from `open` as it tracks pending animations.
overlayRef	Accessor<HTMLElement \| null> The ref of the dialog overlay.
dialogId	Accessor<string> The `id` attribute of the dialog element.
labelId	Accessor<string \| undefined> The `id` attribute of the dialog label element. Is undefined if no `Dialog.Label` is present.
descriptionId	Accessor<string \| undefined> The `id` attribute of the dialog description element. Is undefined if no `Dialog.Description` is present.

RootChildrenProps

Type

Props that are passed to the Root component children callback.

Props

Property	Type/Description
role	'dialog' \| 'alertdialog' The `role` attribute of the dialog element.
open	boolean Whether the dialog is open.
setOpen	Setter<boolean> Change the open state of the dialog.
modal	boolean Whether the dialog should be rendered as a modal.
closeOnEscapeKeyDown	boolean Whether the dialog should close when the user presses the `Escape` key.
closeOnOutsideFocus	boolean Whether the dialog should be closed if a focus event happens outside the bounds of .
closeOnOutsidePointer	boolean Whether the dialog should be closed if the user interacts outside the bounds of the dialog content.
closeOnOutsidePointerStrategy	'pointerdown' \| 'pointerup' Whether `closeOnOutsidePointer` should be triggered on `pointerdown` or `pointerup`.
noOutsidePointerEvents	boolean Whether pointer events outside of should be disabled.
preventScroll	boolean Whether scroll outside of the dialog should be prevented.
hideScrollbar	boolean Whether the scrollbar of the element should be hidden.
preventScrollbarShift	boolean Whether padding should be added to the element to avoid layout shift.
preventScrollbarShiftMode	'padding' \| 'margin' Whether padding or margin should be used to avoid layout shift.
restoreScrollPosition	boolean Whether to restore the scroll position with `window.scrollTo` to avoid possible layout shift after closing the dialog.
allowPinchZoom	boolean Whether the dialog should allow pinch zoom while scroll is disabled.
trapFocus	boolean Whether the dialog should trap focus.
restoreFocus	boolean Whether the dialog should restore focus to the previous active element when it closes.
initialFocusEl	HTMLElement The element to receive focus when the dialog opens.
finalFocusEl	HTMLElement The element to receive focus when the dialog closes.
contentPresent	boolean Whether the dialog content is present. This differes from `open` as it tracks pending animations.
contentRef	HTMLElement \| null The ref of the dialog content.
overlayPresent	boolean Whether the dialog overlay is present. This differes from `open` as it tracks pending animations.
overlayRef	HTMLElement \| null The ref of the dialog overlay.
dialogId	string The `id` attribute of the dialog description element.
labelId	string \| undefined The `id` attribute of the dialog label element. Is undefined if no `Dialog.Label` is present.
descriptionId	string \| undefined The `id` attribute of the dialog description element. Is undefined if no `Dialog.Description` is present.

Developed and designed by Jasmin