Dialog – Once UI

Dialogs are overlay windows that focus user attention on important information, collect input, or require decisions. They appear above the main content and block interaction with the rest of the page until dismissed.

Basic usage

A simple dialog with a title, description, and content.

Dialog

const [isOpen, setIsOpen] = useState(false);

return (
  <>
    <Button onClick={() => setIsOpen(true)}>
      Open Dialog
    </Button>
    <Dialog
      open={isOpen}
      onClose={() => setIsOpen(false)}
      title="Basic dialog"
      description="This is a simple dialog with a title and description."
    >
      <Column fillWidth gap="16" marginTop="12">
        Dialog content goes here. This area can contain any React components.
        <Row fillWidth vertical="center" gap="8">
          <Input
            id="name"
            label="Enter your name"
          />
          <Button label="Submit" onClick={() => setIsOpen(false)}/>
        </Row>
      </Column>
    </Dialog>
  </>
);

Add a footer section to contain action buttons.

Footer

const [isOpen, setIsOpen] = useState(false);

return (
  <>
    <Button variant="secondary" onClick={() => setIsOpen(true)}>
      Dialog with footer
    </Button>
    <Dialog
      open={isOpen}
      onClose={() => setIsOpen(false)}
      title="Dialog with footer"
      footer={
        <>
          <Button variant="secondary" onClick={() => setIsOpen(false)}>
            Cancel
          </Button>
          <Button onClick={() => setIsOpen(false)}>
            Confirm
          </Button>
        </>
      }
    >
      <Text>
        This dialog has a footer with action buttons. The footer is a great place
        for primary and secondary actions.
      </Text>
    </Dialog>
  </>
);

Stacked dialogs

Dialogs can be stacked on top of each other for multi-step interactions. Wrap your app (or the dialog subtree) in DialogProvider so stacked dialogs can coordinate focus and inert behavior on the base dialog.

app/layout.tsx

import { DialogProvider } from '@once-ui-system/core';

export default function Layout({ children }) {
return <DialogProvider>{children}</DialogProvider>;
}

Stacked dialogs

const [isBaseOpen, setIsBaseOpen] = useState(false);
const [isStackedOpen, setIsStackedOpen] = useState(false);

return (
  <DialogProvider>
    <Button variant="secondary" onClick={() => setIsBaseOpen(true)}>
      Open stacked dialogs
    </Button>
    
    <Dialog
      open={isBaseOpen}
      onClose={() => setIsBaseOpen(false)}
      title="Base dialog"
      base={isStackedOpen}
      footer={
        <Row gap="8">
          <Button variant="secondary" onClick={() => setIsBaseOpen(false)}>
            Close
          </Button>
          <Button onClick={() => setIsStackedOpen(true)}>
            Open stacked dialog
          </Button>
        </Row>
      }
    >
      <Text marginBottom="16">
        This is the base dialog. Click the button below to open a stacked dialog on top.
      </Text>
    </Dialog>
    
    <Dialog
      open={isStackedOpen}
      onClose={() => setIsStackedOpen(false)}
      title="Stacked dialog"
      stack
      footer={
        <Button onClick={() => setIsStackedOpen(false)}>Close stacked dialog</Button>
      }
    >
      <Text>
        This is a stacked dialog that appears on top of the base dialog.
        Notice how the base dialog is dimmed in the background.
      </Text>
    </Dialog>
  </DialogProvider>
);

Customized dialog

Dialogs can be customized with Flex props for different visual styles.

Customized dialog

const [isOpen, setIsOpen] = useState(false);

return (
  <>
    <Button variant="danger" onClick={() => setIsOpen(true)}>
      Customized dialog
    </Button>
    <Dialog
      open={isOpen}
      onClose={() => setIsOpen(false)}
      title="Customized dialog"
      maxWidth={48}
      background="danger-weak"
      border="danger-medium"
    >
      <Column fillWidth gap="16">
        <Feedback vertical="center" variant="danger">
          This dialog has custom styling applied through Flex props.
          You can customize the background, border, and other properties.
        </Feedback>
        <Text onBackground="danger-weak">
          Custom content can be added inside the dialog body.
        </Text>
        <Button variant="danger" onClick={() => setIsOpen(false)}>
          Close
        </Button>
      </Column>
    </Dialog>
  </>
);

Flush

Remove the header and use full-bleed media with flush. Use showClose={false} to remove the close button and maxWidth to control the size.

Flush

const [isOpen, setIsOpen] = useState(false);

return (
  <>
    <Button onClick={() => setIsOpen(true)}>
      Flush dialog
    </Button>
    <Dialog
      open={isOpen}
      onClose={() => setIsOpen(false)}
      flush
      showClose={false}
      maxWidth={32}
      title=""
      description=""
    >
      <Media
        src="/images/cover.jpg"
        alt="Cover"
        maxWidth="100%"
        aspectRatio="16/9"
      />
      <Column padding="l" fillWidth gap="12">
        <Heading variant="heading-strong-s">
          Flush dialog
        </Heading>
        <Text variant="body-default-s" onBackground="neutral-weak">
          Header removed. Content is flush to the edges.
        </Text>
      </Column>
    </Dialog>
  </>
);

Close on clickaway

By default, clicking the backdrop closes the dialog. Set closeOnClickaway={false} to require an explicit close action.

Close on clickaway

const [isOpen, setIsOpen] = useState(false);

return (
<>
  <Button variant="secondary" onClick={() => setIsOpen(true)}>
    Dialog without clickaway
  </Button>
  <Dialog
    open={isOpen}
    onClose={() => setIsOpen(false)}
    title="Confirm action"
    closeOnClickaway={false}
    footer={
      <Button onClick={() => setIsOpen(false)}>Close</Button>
    }
  >
    <Text>Clicking outside will not dismiss this dialog.</Text>
  </Dialog>
</>
);

Accessibility

The Dialog component follows accessibility best practices:

Uses role="dialog" and aria-modal="true"
Traps focus within the dialog when open
Supports keyboard navigation and Escape key to close
Provides proper labeling with aria-labelledby
Makes content outside the dialog inert when dialog is open

API reference

	Type	Default
openrequired Whether it is showing.	boolean	—
onCloserequired Called on the close button, Escape, or a click outside.	() => void	—
titlerequired Heading. Required — a dialog with no title is hard to place.	ReactNodestring	—
description Supporting line under the title.	ReactNode	—
children	React.ReactNode	—
footer Pinned below the body, for the actions.	ReactNode	—
base Marks the dialog underneath a stack, which then ignores Escape and click-away while the one above it is open.	boolean	—
stack Marks this as a dialog opened on top of another one.	boolean	—
flush Drop the padding and the top radius, for content that should meet the edges.	boolean	false
showClose Show the close button. Turn it off when only an action should dismiss the dialog.	boolean	!hideClose
hideClose Deprecated: use showClose={false}. Still works through 2.x; showClose wins when both are set.	boolean	false
onHeightChange Called when the body resizes — useful for animating a stack.	(height: number) => void	—
minHeight Lower bound on the body height, in rem.	number	—
closeOnClickaway Close on a click outside.	boolean	true
…and every FlexProps prop	inherited	—

DialogProvider

Wrap your application (or a subtree) when using stacked dialogs.

	Type	Default
childrenrequired	React.ReactNode	—