Dialog

Alpha

An accessible modal dialog with focus trapping, portal rendering, and compound component API.

Import

import { Dialog } from "@compa11y/react";

Usage

Example.tsx
import { useState } from "react";
import { Button, Dialog } from "@compa11y/react";

function Example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>
        Open Dialog
      </Button>

      <Dialog open={open} onOpenChange={setOpen}>
        <Dialog.Title>Confirm Action</Dialog.Title>
        <Dialog.Description>
          Are you sure you want to proceed? This action cannot be undone.
        </Dialog.Description>
        <Dialog.Actions>
          <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
          <Button variant="danger" onClick={() => setOpen(false)}>Confirm</Button>
        </Dialog.Actions>
      </Dialog>
    </>
  );
}

Features

  • Focus trapping within the dialog
  • Focus restoration on close
  • Escape key to close
  • Click outside to close
  • Portal rendering to document body
  • Screen reader announcements
  • Dev warnings for missing title/description
  • Compound component API

Props

Dialog component props
PropTypeDefaultDescription
open*boolean-Controls dialog visibility
onOpenChange*(open: boolean) => void-Called when open state changes
aria-labelstring-Accessible label (alternative to Dialog.Title)
children*ReactNode-Dialog content

Sub-components

Dialog.Title

Dialog.Title props
PropTypeDefaultDescription
children*ReactNode-Title text

Dialog.Description

Dialog.Description props
PropTypeDefaultDescription
children*ReactNode-Description text

Dialog.Actions

Dialog.Actions props
PropTypeDefaultDescription
children*ReactNode-Action buttons

Dialog.Close

Dialog.Close props
PropTypeDefaultDescription
childrenReactNode-Close button content

Keyboard Interactions

Accessibility
All keyboard interactions follow WAI-ARIA best practices and work without any additional configuration.
Keyboard shortcuts for Dialog
KeyAction
TabMoves focus between focusable elements within the dialog
Shift+TabMoves focus backwards
EscapeCloses the dialog