Modals & Dialogs Checklist

Live Demo

Interact with the examples below to see the correct modal behavior in action — focus trapping, loading states, validation, error display, ESC key, and backdrop click.

Confirmation Modal — Delete Action

A destructive confirmation modal with a loading state on the primary action button. ESC key, backdrop click, and the close button all close it.

Form Modal — Add Project

A form modal with field validation, inline error handling, a loading Save button, and a "Trigger Error" button to simulate a server error inside the modal.

1. Opening a Modal

Modal is triggered by a clear user action
Opening animation is present and under 200ms
Background backdrop darkens
Background scroll is locked when modal is open
Focus moves to the modal on open
First focusable element inside the modal receives focus
Screen reader announces modal with role="dialog", aria-modal="true", and aria-labelledby

2. Closing a Modal

Close button visible in top-right corner
Clicking backdrop closes modal unless unsaved form protection applies
Escape key closes modal
Closing animation matches open animation
Focus returns to the trigger button on close
Background scroll restored on close
Unsaved changes show Discard changes confirmation before closing
Escape/backdrop disabled while loading operation is in progress

3. Modal Content Structure

Modal has visible title using h2 or h3
Title connected via aria-labelledby
Modal has clear primary action and cancel/close button
Primary action on the right, cancel on the left or bottom
Destructive primary actions styled red/danger
Modal content scrolls internally, not the page behind it
Modal width appropriate for content
Modal centered vertically and horizontally
Modal does not exceed viewport height without internal scroll

4. Confirmation Modals

Used before destructive or irreversible actions like delete, archive, or remove member.

Title states action: Delete Project?, not Are you sure?
Body explains consequence
Body names the specific item
Primary button label states the action
Cancel button clearly visible and labeled Cancel
Primary button is danger/red for destructive action
Loading state on primary button
On success: modal closes, success toast shown, list refreshes
On error: modal stays open, error shown inside modal

5. Form Modals

Same component used for Add and Edit
Form validation runs before submission
API/server errors shown inside modal
Loading state on submit button
No double submit possible
On success: modal closes, success toast shown, parent list refreshes
On error: modal stays open, form stays populated, error shown
Cancel confirms discard if form has unsaved input
Long form modal scrolls internally
Tab order loops inside the modal

6. Accessibility

role="dialog" on modal root
aria-modal="true" on modal root
aria-labelledby points to modal title
aria-describedby points to modal body if applicable
Focus trapped inside modal
Escape key closes modal
Focus returns to trigger element on close
Background content has aria-hidden="true" while modal is open
All interactive elements inside modal are keyboard-accessible

Before Marking Done

Modal open, close, focus trap, Escape behavior, scroll lock, loading state, error state, accessibility, and mobile behavior must all be tested.