bellhop by actabl
Modal

When to use

Use modals for critical tasks that require user focus or confirmation before proceeding.

Confirmations

Ask users to confirm destructive or important actions like deletions or permanent changes.

Quick Forms

Collect focused input without navigating away from the current page, like adding a new item.

Critical Information

Display important messages, warnings, or alerts that demand immediate user attention.

Multi-Step Workflows

Guide users through short, focused processes that require multiple steps or decisions.

When not to use

  • For non-essential information that doesn't require interrupting the user's workflow—use a notification or tooltip instead
  • For complex, multi-page forms—use a dedicated page or wizard interface for better usability
  • When users need to reference information while filling a form—use an inline expandable section or side panel
  • For frequent actions that don't need confirmation—allow direct action with an undo option

Anatomy

Modals consist of an overlay backdrop, dialog container, and structured content areas.

  1. Backdrop

    Semi-transparent overlay covering the page content behind the modal

  2. Modal Container

    White dialog box positioned in the center of the viewport

  3. Header

    Title and optional icon or close button at the top

  4. Content

    Main body area containing the message, form, or other content

  5. Footer Actions

    Action buttons typically including Cancel and a primary action

  6. Close Button

    X icon button in the top-right corner for dismissing the modal

Types

Modals come in different semantic types and sizes for various use cases.

Default

Standard modal for general-purpose dialogs and information display.

Cancel Confirm

Success

Confirm successful completion of an action with a success icon.

Done

Warning

Alert users about potential issues or actions requiring caution.

Cancel Continue

Error

Communicate errors or critical issues that need immediate attention.

Cancel Retry

Destructive

Confirm dangerous actions like permanent deletions with prominent warning styling.

Cancel Delete Account

Large Modal

Larger variant for forms or content requiring more space.

Cancel Create Project

Interaction

Modals can be dismissed in multiple ways while managing focus and preventing background interaction.

Opening

Modal appears with a fade-in animation and traps focus within the dialog.

Dismissal Methods

Close via X button, Cancel button, Escape key, or clicking the backdrop.

Focus Trap

Keyboard navigation cycles through modal elements, preventing interaction with background content.

Action Confirmation

Primary action button completes the task and closes the modal with appropriate feedback.

Placement

Modals appear centered over the current page in the viewport.

Centered Positioning

Modals are always centered both horizontally and vertically in the viewport.

Stacking Context

Modals appear above all other page content with high z-index values.

Responsive Sizing

Modal width adapts to viewport size, expanding to near full-width on mobile devices.

Scrollable Content

Long content scrolls within the modal body while header and footer remain fixed.

Accessibility

Modals follow WAI-ARIA dialog pattern with focus management and keyboard support.

Keyboard Support

  • Escape: Close the modal and return focus to the trigger element
  • Tab: Cycle through focusable elements within the modal
  • Shift+Tab: Reverse tab through modal elements
  • Focus is trapped within the modal until it's closed

ARIA Attributes

  • role="dialog": Identifies the modal as a dialog
  • aria-modal="true": Indicates content outside is inert
  • aria-labelledby: Associates modal with its title
  • aria-describedby: Associates modal with its description

Focus Management

  • Focus moves to the first focusable element when modal opens
  • Focus returns to trigger element when modal closes
  • Tab navigation cycles within modal boundaries
  • Background content is inert and cannot receive focus

Screen Reader Support

  • Modal opening is announced to screen readers
  • Modal title and description are associated and read aloud
  • Action buttons have clear, descriptive labels
  • Closing actions are announced when modal dismisses

Resources

Design and development resources for the Modal component.

Figma

Available
View in Figma →

Web Components/Angular

Available
View in Storybook →

React

Available
View in Storybook →