Dialog

ContainersComposerBuilt

Blocking and non-blocking overlay container.

Also known as:
  • Modal
  • Confirm Dialog
  • Feedback
  • Inline Dialog
  • Inline Message
  • Callout
  • Highlight
  • Hint
  • Note
  • Callout card
  • Dialogue
  • Highlight box
  • Highlighter
  • Input dialog
  • Notes
  • Notice
  • User feedback
  • Modal Dialog
  • Pop-up Dialog
  • Alert Dialog
  • Confirmation Dialog

Overview

Purpose

The Dialog component blocking and non-blocking overlay container.within our design system. It follows our composer layer principles, ensuring consistency and reusability across applications.

When to Use

  • Use when you need organizing content
  • Appropriate for containers contexts
  • Follows composer component patterns

When Not to Use

  • Avoid when simpler alternatives exist
  • Don't use for interactive elements
  • Consider alternatives for edge cases

Live Example

import React from 'react';
import Dialog from './components/Dialog';
import props from '/props.json';

export default function App() {
  return (
    <div style={{ padding: '2rem', display: 'flex', alignItems: 'center', justifyContent: 'center', minHeight: '100vh' }}>
      <Dialog {...props}>
        {props.children || 'Example dialog content'}
      </Dialog>
    </div>
  );
}
Open on CodeSandboxOpen Sandbox

Anatomy

Understanding the structure of the Dialog component helps ensure proper implementation and customization.

Property Description Type
rootOutermost container that hosts the component.Root
bodyBody region of the component.Slot
closeButtonClose button region of the component.Slot
footerFooter region of the component.Slot
headerHeader region of the component.Slot
titleTitle region of the component.Slot
backdropBackdrop region of the component.Part
modalWhen true (default), renders a modal dialog with backdrop and focus trap. When false, renders a non-modal dialog.boolean | undefined
closeClose region of the component.Part

Variants & States

import React from 'react';
import Dialog from './components/Dialog';
import props from '/props.json';

export default function App() {
  return (
    <div style={{ padding: '2rem', display: 'flex', alignItems: 'center', justifyContent: 'center', minHeight: '100vh' }}>
      <Dialog {...props}>
        {props.children || 'Example dialog content'}
      </Dialog>
    </div>
  );
}
Open on CodeSandboxOpen Sandbox

API Reference

Props

NameTypeRequiredDefaultDescription
modalbooleanNotrue—
sizeDialogSizeNo'md'—
classNamestringNo''—
childrenReact.ReactNodeYes'×'—
onClose() => voidNo——
closeOnBackdropClickbooleanNotrue—
closeOnEscapebooleanNotrue—
initialFocusstringNo——
returnFocusstringNo——

Accessibility

Standards Compliance

This component follows WCAG 2.1 AA guidelines and includes proper ARIA attributes, keyboard navigation, and screen reader support.

Common Pitfalls

  • Not trapping focus
  • poor mobile handling
  • misuse for inline content.

Accessibility Checklist

  • ○ Keyboard navigation support
  • ○ Screen reader compatibility
  • ○ Color contrast compliance
  • ○ Focus management
  • ○ ARIA attributes
  • ○ Reduced motion support

Usage Guidelines

✓ Do

  • Use consistent spacing and sizing
  • Follow established patterns
  • Provide clear labels and descriptions
  • Test with assistive technologies

✗ Don't

  • Override core functionality
  • Use without proper context
  • Ignore accessibility requirements
  • Modify without design system approval

Examples

Basic Usage

Simple implementation with default props and common configurations.

import React from 'react';
import Dialog from './components/Dialog';
import props from '/props.json';

export default function App() {
  return (
    <div style={{ padding: '2rem', display: 'flex', alignItems: 'center', justifyContent: 'center', minHeight: '100vh' }}>
      <Dialog {...props}>
        {props.children || 'Example dialog content'}
      </Dialog>
    </div>
  );
}
Open on CodeSandboxOpen Sandbox

Advanced Usage

Complex patterns including composition, state management, and real-world scenarios.

import React from 'react';

export default function App() {
  return (
    <div style={{ 
      padding: '2rem', 
      display: 'flex',
      flexDirection: 'column',
      gap: '1.5rem'
    }}>
      <h3>Dialog - Advanced Patterns</h3>
      <p>Advanced usage patterns for Dialog include:</p>
      <ul>
        <li>Composition with other components</li>
        <li>Custom styling and theming</li>
        <li>Controlled vs uncontrolled patterns</li>
        <li>Form integration</li>
        <li>Accessibility enhancements</li>
      </ul>
      <p style={{ color: '#6b7280', fontStyle: 'italic' }}>
        Full advanced examples coming soon.
      </p>
    </div>
  );
}
Open on CodeSandboxOpen Sandbox

Development Tools

Use these tools to analyze the component's performance, design tokens, and accessibility during development.

Contribute

Help us improve the Dialog component documentation. Found an issue or have suggestions?

Edit this pageReport an issueContribution guidelines

Related Components

Accordion

Expand/collapse grouped sections.

Containers • composers

Drawer

Sliding overlay.

Containers • composers

Modal

Blocking and non-blocking overlay container.

Containers • composers

Popover

Anchored floating UI.

Containers • composers

Sidebar

Sliding overlay.

Containers • composers

Action Bar

Groups actions with priority + overflow.

Actions • composers