Overlay Manager

Usage

The createOverlay function creates a new overlay component that can be programmatically controlled.

import { createOverlay } from "@chakra-ui/react"

const dialog = createOverlay<DialogProps>((props) => {
  const { title, description, content, ...rest } = props
  return (
    <Dialog.Root {...rest}>
      <Portal>
        <Dialog.Backdrop />
        <Dialog.Positioner>
          <Dialog.Content>
            {title && (
              <Dialog.Header>
                <Dialog.Title>{title}</Dialog.Title>
              </Dialog.Header>
            )}
            <Dialog.Body spaceY="4">
              {description && (
                <Dialog.Description>{description}</Dialog.Description>
              )}
              {content}
            </Dialog.Body>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
})

Then render the Viewport component to see the overlay.

<dialog.Viewport />

Examples

Dialog

Here's an example of a dialog component that can be programmatically controlled.

Drawer

Here's an example of a drawer component that can be programmatically controlled.

Update

Use the .update method to update the props of an overlay.

Return Value

Awaiting the result of the .open() method returns the value passed to the .close() method.

:::info

Bonus: You can also use the .waitForExit() method to wait for the exit animation to complete before opening a new overlay.

:::

Open Dialog from Menu Item

Use the overlay manager to manage dialogs that can be opened from menu items. The .open() method can be called to open the dialog.

This approach avoids unexpected close behavior caused by event bubbling and portals.

Programmatic Closing

You can close an overlay from within the component itself by calling the injected onOpenChange prop with { open: false }.

This is useful for scenarios like form submissions or user interactions that should close the overlay.

const dialog = createOverlay<DialogProps>((props) => {
  const { onOpenChange, ...rest } = props

  const handleSubmit = () => {
    // Close the overlay after successful action
    onOpenChange?.({ open: false })
  }

  return <Dialog.Root {...rest}></Dialog.Root>
})

API

Props

Props that are injected into the overlay component by the createOverlay function:

• open: Whether the overlay is currently open
• onOpenChange: Callback fired when the overlay's open state changes
• onExitComplete: Callback fired when the overlay's exit animation completes

Methods

Viewport

The root component that renders all active overlays.

open(id, props)

Opens a new overlay with the given id and props. Returns a promise that resolves with any value.

close(id, value)

Closes the overlay with the given id and returns a promise that resolves when closed.

update(id, props)

Updates the props of the overlay with the given id.

remove(id)

Removes the overlay with the given id.

removeAll()

Removes all overlays.

get(id)

Gets the props of the overlay with the given id.

getSnapshot()

Gets the current snapshot of the overlays.

waitForExit(id)

Waits for the exit animation to complete for the overlay with the given id.