# Modal

> Use when you need to display focused content or actions.

- Skill: `thedaviddias/modal` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add thedaviddias/modal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thedaviddias/modal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thedaviddias (https://skillmd.com/u/thedaviddias)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thedaviddias/modal

---


# Modal

Display focused content or actions

## What it solves

A **modal** appears on top of the main application screen, blocking page interaction until closed.
Modals display important information, request user input, or confirm actions in a focused way.

## When to use

Use modals to **interrupt user flow** for important information or required user input before proceeding.
**Common scenarios include:**
- **Confirmation dialogs** – "Are you sure you want to delete this item?"
- **Critical system messages** – session expiration warnings, important alerts
- **Forms requiring user input** – login, payment, or signup flows
- **Media previews** – images or videos in lightbox overlays
- **Multi-step processes** – checkout steps or onboarding flows
- **Terms and conditions** – requiring user agreement before proceeding

## When to avoid

- Non-essential information doesn't need immediate attention
- Content or interaction fits inline on the page
- Same information needs frequent access
- Large content requires significant scrolling - dedicated pages work better for UX and accessibility
- Users must interact with the main page while modal is open

## Implementation workflow

1. Confirm the pattern matches the problem and constraints before copying the example.
2. Start from the anatomy and examples in `references/pattern.md`, then choose the smallest viable variation.
3. Apply accessibility, performance, and interaction guardrails before layering visual polish.
4. Use the testing guidance to verify behavior across keyboard, screen reader, responsive, and failure scenarios.

## Accessibility guardrails

### Keyboard Interaction Pattern
The following table outlines the standard keyboard interactions for modal components. These interactions ensure that users can navigate and operate modals effectively using only a keyboard.
| Key         | Action                                                                                               |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| Escape      | Closes the modal                                                                                     |
| Tab         | Moves focus to the next focusable element within the modal. Focus should be trapped within the modal |
| Shift + Tab | Moves focus to the previous focusable element within the modal                                       |
| Enter/Space | Activates the focused button or control                                                              |
> **Note**: When the modal opens, focus should automatically move to the first focusable element within the modal (usually the close button or the first form field). When the modal closes, focus should return to the element that triggered the modal.

## Common mistakes

### Forcing Users Into a Modal (No Close Option)
**The Problem:**
Users feel trapped if they can't exit a modal.

**How to Fix It?**
Always provide a clear **close button (X)** and support the `Esc` key for dismissal.

### Triggering Modals on Page Load
**The Problem:**
Unrequested modals on page load can feel like pop-ups that disrupt user flow.

**How to Fix It?**
Only show modals when the user **intentionally** initiates them.

### Disrupting Background Page Focus
**The Problem:**
Some modals allow interaction with background content while open, causing layered focus.

**How to Fix It?**
Add a **focus trap** inside the modal and prevent background interaction until it's closed.

## Related patterns

- https://uxpatterns.dev/patterns/content-management/popover
- https://uxpatterns.dev/patterns/content-management/tooltip
- https://uxpatterns.dev/patterns/user-feedback/loading-indicator

---

For full implementation detail, examples, and testing notes, see `references/pattern.md`.

Pattern page: https://uxpatterns.dev/patterns/content-management/modal