Dialog

The Dialog component is a modal that can be used to display content in a controlled manner.

import {
  Dialog,
  DialogTrigger,
  DialogHeading,
  DialogDescription,
  DialogCloseTrigger,
  DialogCloseIconTrigger,
} from '@cerberus/react'

Usage

To use the Dialog component, wrap it in a DialogProvider and use the DialogTrigger component to open the dialog. The Dialog component is a controlled component that can be used to display content in a modal.

import { Model } from '@carbon/icons-react'
import {
  DialogProvider,
  Dialog,
  DialogTrigger,
  DialogCloseTrigger,
  DialogCloseIconTrigger,
  DialogHeading,
  DialogDescription,
  Button,
} from '@cerberus/react'
import { VStack, HStack } from 'styled-system/jsx'

function OverviewPreview() {
  return (
    <DialogProvider>
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Dialog>
        <DialogCloseIconTrigger />
        <VStack alignItems="flex-start" gap="xs" w="full">
          <DialogHeading>Dialog Title</DialogHeading>
          <DialogDescription>
            This is a custom modal description
          </DialogDescription>
        </VStack>

        <HStack paddingBlock="10" w="full">
          <Model size="5rem" />
          <Model size="5rem" />
          <Model size="5rem" />
        </HStack>

        <DialogCloseTrigger asChild>
          <Button>Close</Button>
        </DialogCloseTrigger>
      </Dialog>
    </DialogProvider>
  )
}

With DatePicker

import { Model } from '@carbon/icons-react'
import {
  DialogProvider,
  Dialog,
  DialogTrigger,
  DialogCloseTrigger,
  DialogCloseIconTrigger,
  DialogHeading,
  DialogDescription,
  Button,
} from '@cerberus/react'
import { VStack, HStack } from 'styled-system/jsx'

function ModalFormPreview() {
  return (
    <DialogProvider lazyMount>
      <DialogTrigger asChild>
        <Button>open lazy mounted form dialog</Button>
      </DialogTrigger>
      <Dialog>
        <DialogHeading>Form Dialog</DialogHeading>
        <DialogDescription>
          This is a form dialog with a date picker
        </DialogDescription>

        <Box paddingBlock="10" w="full">
          <form>
            <Field>
              <DatePicker id="modal-form-picker" name="modal-form-picker">
                <DatePickerLabel>Start date</DatePickerLabel>
                <DatePickerInput />
                <DatePickerCalendar />
              </DatePicker>
            </Field>
          </form>

          <Box paddingBlockStart="10">
            <DialogCloseTrigger asChild>
              <Button>Submit</Button>
            </DialogCloseTrigger>
          </Box>
        </Box>
        <DialogCloseIconTrigger />
      </Dialog>
    </DialogProvider>
  )
}

Sizes

The Dialog component supports different sizes. You can set the size prop to xs to lg, or full.

import {
  Button,
  DialogProvider,
  Dialog,
  DialogTrigger,
  DialogCloseIconTrigger,
  DialogProps,
  type DialogProps
} from '@cerberus/react'
import { VStack, HStack } from 'styled-system/jsx'
import { Model } from '@carbon/icons-react'

function DialogContent(props: { size: DialogProps['size'] }) {
  return (
    <DialogProvider>
      <DialogTrigger asChild>
        <Button>open {props.size} size</Button>
      </DialogTrigger>

      <Dialog size={props.size}>
        <DialogCloseIconTrigger />
        <VStack alignItems="flex-start" gap="xs" w="full">
          <DialogHeading>Dialog Title</DialogHeading>
          <DialogDescription>
            This is a custom modal description
          </DialogDescription>
        </VStack>

        <HStack paddingBlock="10" w="full">
          <Model size="5rem" />
          <Model size="5rem" />
          <Model size="5rem" />
        </HStack>
      </Dialog>
    </DialogProvider>
  )
}

Primitives

You can utilize the primitive components or the css prop to customize the dialog.

Component	Description
DialogProvider	The main state context for the dialog.
DialogTrigger	The trigger element that opens the dialog.
DialogBackdrop	The backdrop that covers the page when the dialog is open.
DialogPositioner	The container that positions the dialog content.
DialogContent	The content that is shown within the dialog.
DialogHeading	The heading title of the dialog.
DialogDescription	The description of the dialog.
DialogCloseTrigger	The trigger element that closes the dialog.
DialogCloseIconTrigger	The trigger element that closes the dialog with an "x" icon.

import { DialogParts, Button, Portal } from '@cerberus/react'

function CustomPreview() {
  return (
    <DialogParts.Root>
      <DialogParts.Trigger asChild>
        <Button palette="danger">Custom Dialog</Button>
      </DialogParts.Trigger>

      <Portal>
        <DialogParts.Backdrop
          css={{
            animationFillMode: 'forwards',
            bgColor: 'danger.surface.initial/70',
            bottom: 0,
            left: 0,
            opacity: 0,
            position: 'fixed',
            right: 0,
            top: 0,
            zIndex: 'overlay',
            _open: {
              animationStyle: 'emphasized-fade-in',
            },
            _closed: {
              animationStyle: 'emphasized-fade-out',
            },
          }}
        />
        <DialogParts.Positioner
          css={{
            alignItems: 'flex-start',
            display: 'flex',
            h: '100dvh',
            justifyContent: 'center',
            left: '0',
            paddingBlockStart: 'xl',
            position: 'fixed',
            top: '0',
            w: '100vw',
            zIndex: 'modal',
          }}
        >
          <DialogParts.Content
            css={{
              bgColor: 'page.surface.initial',
              padding: 'xl',
            }}
          >
            <DialogParts.Heading
              css={{
                paddingBlockEnd: 'lg',
              }}
            >
              C3rB3RuS R00lz!
            </DialogParts.Heading>
            <DialogParts.CloseTrigger asChild>
              <Button palette="danger" shape="rounded">
                Close
              </Button>
            </DialogParts.CloseTrigger>
          </DialogParts.Content>
        </DialogParts.Positioner>
      </Portal>
    </DialogParts.Root>
  )
}

API

Props

The Dialog component is an abstraction of the primitives and accepts the following props:

Name	Default	Description
size	`sm`	This size of the Dialog.

The Dialog component also accepts all the props of the DialogContent primitive props

Parts

The DialogParts API is an Object containing the full family of components.

Name	Description
Root	The `DialogRoot` primitive and context provider for the family.
Trigger	The `DialogTrigger` trigger element that opens the dialog.
Backdrop	The `DialogBackdrop` that covers the page when the dialog is open.
Positioner	The `DialogPositioner` and container that positions the dialog content.
Content	The `DialogContent` that is shown within the dialog.
Heading	The `DialogHeading` which is the heading of the dialog.
Description	The `DialogDescription` and description of the dialog.
CloseTrigger	The `DialogCloseTrigger` trigger element that closes the dialog.

On this page

Edit this page on Github