Dialog

A modal sheet that covers the page until it is answered. Use it to confirm an action or to take input that has to interrupt the flow.

import { Button, Dialog, DialogClose } from 'neba';

<Dialog
  trigger={<Button color="danger">Delete workspace</Button>}
  title="Delete this workspace?"
  description="Every project, deploy and log inside it goes with it."
  actions={<DialogClose render={<Button color="danger">Delete</Button>} />}
>
  This cannot be undone.
</Dialog>;

Props

Prop	Type	Default	Description
locale	string	—	BCP 47 tag naming the × in that language. Unsupported tags fall back to English
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The type scale, the padding, and how wide the sheet may get. One axis rather than a second scale spelled maxWidth
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. The sheet is never dyed, so it reaches the edge and the focus ring
densityshared	'default' | 'compact'	'default'	Padding only
open	boolean	—	Whether it is shown. With onOpenChange, a controlled dialog
defaultOpen	boolean	false	The initial state of an uncontrolled dialog
onOpenChange	(open: boolean) => void	—	Called when it opens or closes
trigger	ReactElement	—	The element that opens it, wired up by Base UI. Optional: a controlled dialog opened elsewhere needs none
title	ReactNode	—	The heading. Rendered as the h2 that names the dialog
description	ReactNode	—	A line under the title, and the dialog's accessible description
actions	ReactNode	—	The bottom row, end-aligned. DialogClose is what makes one of them dismiss
dividers	boolean	false	Separates the sections with hairlines instead of space. Worth turning on the moment the body scrolls
showClose	boolean	true	The × in the corner. On by default, unlike most booleans here: a modal takes the page away, and the way out should be visible
closeLabel	string	—	Accessible name of the × button
width	number | string	—	A hard cap overriding the one size implies. Numbers are pixels
fullWidth	boolean	true	Takes the full width its size allows. On by default, the other way round from everywhere else: a dialog’s container is the viewport
fullScreen	boolean	false	Fills the viewport edge to edge
modal	boolean | 'trap-focus'	true	Whether the page behind is taken away. 'trap-focus' keeps it scrollable and clickable while holding focus inside
dismissible	boolean	true	Whether Escape and an outside click close it. Turn it off only with actions that answer it
children	ReactNode	—	The body: the only part that scrolls
classNames	NebaSlots<'backdrop' | 'viewport' | 'title' | 'description' | 'close' | 'body' | 'actions'>	—	Class names for the parts behind the root. The root itself is className, so there is no root key

Native <div> attributes pass through to the popup. Only color, title and children are excluded, since the table above spells them differently.

There is no variant and no elevation: a modal always carries a level-3 shadow.

Examples

size and width

size sets the type scale and the padding along with the sheet's maximum width. When you need to break that pairing (small type on a wide sheet for a table or a diff), set a length in width.

import { Button, Dialog, DialogClose } from 'neba';
import type { NebaSize } from 'neba';

const SIZES: NebaSize[] = ['xs', 'sm', 'md', 'lg', 'xl'];

export default function DialogSizes() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      {SIZES.map((size) => (
        <Dialog
          key={size}
          size={size}
          trigger={
            <Button size="sm" variant="outline" color="secondary">
              {size}
            </Button>
          }
          title={`A ${size} dialog`}
          description="The size sets the type scale, the padding and the width it is allowed to reach."
          actions={<DialogClose render={<Button size="sm">Close</Button>} />}
        >
          One axis rather than two: there is no separate `maxWidth` to keep in step with `size`.
        </Dialog>
      ))}
    </div>
  );
}

dividers

With a long body, only the body scrolls; the heading and the actions stay put. dividers rules those boundaries, which is what shows the header did not scroll away.

import { Button, Dialog, DialogClose } from 'neba';

const TERMS = Array.from({ length: 12 }, (_, index) => ({
  heading: `${index + 1}. Clause ${index + 1}`,
  body: 'The header and the actions stay put while this part scrolls, which is what the hairlines are there to say.'
}));

export default function DialogScrolling() {
  return (
    <Dialog
      dividers
      size="lg"
      trigger={<Button variant="outline">Read the terms</Button>}
      title="Terms of service"
      description="Last updated 2 March"
      actions={
        <>
          <DialogClose
            render={
              <Button variant="text" color="secondary">
                Decline
              </Button>
            }
          />
          <DialogClose render={<Button>Accept</Button>} />
        </>
      }
    >
      <div className="flex flex-col gap-4">
        {TERMS.map((term) => (
          <div key={term.heading} className="flex flex-col gap-1">
            <div className="font-semibold">{term.heading}</div>
            <p className="text-(--neba-muted-fg)">{term.body}</p>
          </div>
        ))}
      </div>
    </Dialog>
  );
}

dismissible

dismissible={false} blocks both Escape and the click outside. Turn it off only when actions holds a button that answers the dialog: otherwise there is no way out.

import { useState } from 'react';
import { Button, Dialog, TextField } from 'neba';

export default function DialogControlled() {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState('');

  const confirmed = name === 'neba';

  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button color="danger" onClick={() => setOpen(true)}>
        Delete project
      </Button>

      {/* Not dismissible: no Escape, no click outside. A dialog that has to be
          answered needs actions that answer it, and this one has both. */}
      <Dialog
        open={open}
        onOpenChange={setOpen}
        dismissible={false}
        showClose={false}
        size="sm"
        color="danger"
        title="Type the project name"
        description="This is the last step before it is gone."
        actions={
          <>
            <Button variant="text" color="secondary" onClick={() => setOpen(false)}>
              Cancel
            </Button>
            <Button color="danger" disabled={!confirmed} onClick={() => setOpen(false)}>
              Delete
            </Button>
          </>
        }
      >
        <TextField
          fullWidth
          label="Project name"
          placeholder="neba"
          value={name}
          onChange={(event) => setName(event.target.value)}
        />
      </Dialog>
    </div>
  );
}

DialogClose

Closes the dialog from a button without owning the open state yourself. Use render to put the control you want inside it.

actions={
  <>
    <DialogClose render={<Button variant="text" color="secondary">Cancel</Button>} />
    <DialogClose render={<Button color="danger">Delete</Button>} />
  </>
}

classNames

className lands on the popup: the sheet itself, which is what a caller means by "the dialog". Everything around and inside it is reached through classNames.

<Dialog
  title="Delete this?"
  classNames={{ backdrop: 'backdrop-blur-none', actions: 'justify-between' }}
/>

The slots are backdrop, viewport, title, description, close, body and actions. The first two are the ones with no other way in: both render at the end of <body>, outside the popup, so no selector written against the sheet finds them. See prop conventions for how a class name you pass resolves against the component's own.

Accessibility

• title and description are wired into aria-labelledby and aria-describedby. The title renders as a real <h2>.
• The focus trap, the scroll lock, the inert page behind, and focus returning to the trigger on close are all handled.
• showClose is on by default. The way out of a modal should always be visible, and it is also what a touch screen reader uses to escape the popup.
• locale decides the ×'s accessible name; closeLabel writes it out instead.