Skip to content
SkillCodex
Menu

Alert dialog

Alert dialog

A modal dialog that interrupts a consequential action and requires an explicit confirm or cancel decision.

Try the component
Context, sources and actions
Sources and revision
Updated
Version
v1.0.26 · r2
Sources
5 sources
Status
Published
Read the sources

You may have searched for: ask before permanently deleting thisa warning box with cancel and deletemake me confirm a dangerous action

All phrasings
Save and share

Recognize

Modal surfaces

Try it

Is the task about acting, confirming a consequential decision, or viewing media?

Alert dialog

Shared trial context

A project item opens a focused overlay while the underlying workspace remains unavailable until the user finishes or closes it.

Alert dialog

Mission

Alert dialog

Open the warning, read the named consequence, cancel with the keyboard, then reopen and confirm deliberately.

Live result

The workspace is intact. No decision is being requested.

Step 1 of 3

Try

Try the component. Your live result appears just above. Move on at your own pace.

Behavior and edge case
What to observe
The warning names the workspace, explains permanent loss, and initially focuses the safer Keep it action.
Edge case
While deletion is submitting, both actions prevent duplicate activation and the dialog reports the pending state.

What this example shows

An Alert dialog is for a short consequential decision, not a general form and not a media viewer.

Which fits your need?

Alert dialog

Confirming a permanent deletion

Modal dialog

Editing a compact record without losing page context

Which component will you use here?
Difference and sources

An Alert dialog is for a short consequential decision, not a general form and not a media viewer.

Read the sources

    Parts of the specimen

    Select a numbered marker on the schematic, or use the list below, to see its role. The schematic shows the concept's representative state.

    Backdrop

    The layer that separates a modal surface from inactive page content.

    Position in the atlas

    Relationship map

    Locate the chapter, neighboring concepts, and the next useful decision.

    • Chapter

      Modal surfaces

      Alert dialog belongs to this comparison group.

    • Do not confuse

      Modal dialog

      Choose Alert dialog if the user must confirm or cancel a consequential action, with no other input. Choose Modal dialog if the task needs several fields or steps while the page stays in the background.

      Compare this pair
    • Do not confuse

      Lightbox

      Choose Alert dialog if the user must decide before a consequential action. Choose Lightbox if viewing media at a larger size is the task, with no consequential decision.

      Compare this pair
    • Next step

      Compare the concepts in the chapter before choosing an implementation.

      Open the chapter

    In your own words

    Understand

    What people describe

    Documented aliases: confirmation dialog, destructive confirmation, warning dialog

    • ask before permanently deleting this
    • a warning box with cancel and delete
    • make me confirm a dangerous action
    • stop the flow until I choose
    • a final check before removing the account
    • confirm or cancel something irreversible

    Choose

    Use it when

    • Confirming a permanent deletion
    • Warning that leaving will discard meaningful unsaved work

    Avoid it when

    • The action can be safely undone
    • The message only reports a result and needs no decision

    Compare

    Compare similar concepts

    Platform equivalents

    The same interaction can have a different name or contract on each platform. Check the mapping before choosing an API.

    • HTML

      Partial

      <dialog role="alertdialog">

      HTML Living Standard 2026-09

      The dialog element supplies modality; alert urgency, message association, and safe focus placement must be authored.

      Verified Official documentation
    • WAI-ARIA APG

      Direct

      role="alertdialog"

      WAI-ARIA APG 2026-09

      The pattern specializes a modal dialog for an important message that requires a response.

      Verified Official documentation
    • Radix UI

      Direct

      AlertDialog.Root

      @radix-ui/react-alert-dialog 1.1.x

      The primitive keeps the alert dialog modal and requires an explicit response before dismissal.

      Verified Official documentation
    • shadcn/ui

      Direct

      AlertDialog

      shadcn/ui docs 2026-09-03

      The Alert Dialog recipe exposes the dedicated Radix alert-dialog primitive.

      Verified Official documentation
    • Material UI

      Partial

      Dialog

      Material UI v9.4.0

      MUI has no separate AlertDialog component; Dialog must be given the urgent message, role, and safe actions.

      Verified Official documentation
    • SwiftUI

      Direct

      .alert

      SwiftUI documentation 2026-09

      The alert modifier presents a system alert with platform-managed actions and dismissal.

      Verified Official documentation
    • Jetpack Compose

      False friend

      AlertDialog

      Android Developers 2026-08

      Despite its name, AlertDialog is the general ready-made dialog; it does not enforce a destructive-confirmation contract.

      Verified Official documentation
    • Flutter

      Partial

      AlertDialog

      Flutter API docs 2026-09

      AlertDialog supplies the Material layout, but urgency, action safety, and non-dismissal must be configured.

      Verified Official documentation

    Impact profile

    Measured implementation costs and operating constraints for this SkillCodex specimen. A missing evaluation is never treated as free.

    Rendering
    Client
    Lazy weight
    15 kB-gzip
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Sum of gzip -9 bytes for the lazy files of module 29012 in .next/server/app/(en)/term/[slug]/page/react-loadable-manifest.json after pnpm build:local at c9f1299.
    Low-end devices
    Fine
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Loaded the 390 x 844 term route in isolated Chromium with 6x CPU throttling and reduced motion, then exercised the first state change; failures are recorded as non-blocking warnings.
    CPU / GPU
    React state and a Radix DOM portal hold the decision surface; no canvas or WebGL path is present.
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Static source inspection of the target lab module plus an interaction on the isolated Chromium verification route; checked DOM/React work and absence of canvas or WebGL.
    Reduced motion
    The global reduced-motion contract collapses animation and transition durations; the same states and controls remain available.
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Inspected src/app/globals.css prefers-reduced-motion rules and repeated the target interaction with reducedMotion=reduce in Chromium.
    Static fallback
    Without JavaScript, the term route stays on its localized Loading fallback; the profile and initial specimen are not revealed.
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Loaded all ten prerendered routes from a local next start build in Chromium with JavaScript disabled; each HTTP 200 remained on the localized Loading fallback, so the profile and specimen were not revealed.
    Server rendering
    Hydrates
    Measured ·
    Environment
    macOS 26.6.2; Node 24.19.0; pnpm 10.34.5; Next.js 16.3.0 Turbopack; Chromium 140
    Method
    Inspected the prerendered route response, then loaded the same route with JavaScript enabled and exercised the hydrated client specimen.
    Maintenance
    Stable

    Good fit

    • Irreversible or high-consequence actions that require confirm or cancel.

    Avoid when

    • Non-blocking status messages or safely reversible actions.

    Verification checklist

    Try these actions in the lab, then check the same behaviours in your agent’s result. Adapt the example names to your interface.

    1. 1. Do this

      Open the destructive-action warning using disposable test data and read it before choosing.

      Expected result

      The message identifies what will be affected and the consequence; the safer useful action receives initial focus.

    2. 2. Do this

      Choose Cancel, reopen the warning, then move between its controls with Tab.

      Expected result

      Cancellation changes no data, returns focus to the opener, and the reopened warning keeps keyboard focus inside it.

    3. 3. Do this

      Confirm the action on the test data and try activating confirmation again while it is pending.

      Expected result

      The action runs only once, its pending state is clear, and the result is stated before you continue.

    Full contract
    1. 1The message names the exact consequence
    2. 2Confirm and Cancel are explicit and visually distinct
    3. 3Initial focus avoids accidental destructive confirmation
    4. 4The alert cannot disappear before a decision

    Understand → Recognize → Choose → Compare

    Pack for your agent

    Pre-written instructions to paste into your agent. Copying executes nothing.

    Implement correctly

    Build Alert dialog without breaking its behavior

    # Implement Alert dialog in your agent
    
    ## Objective
    Implement Alert dialog for this verified behavior: A modal dialog that interrupts a consequential action and requires an explicit confirm or cancel decision.
    
    ## Prerequisites
    - Inspect the repository, design system, and existing tests first.
    - Preserve unrelated changes and keep the file scope bounded.
    - Confirm that Alert dialog matches the need before writing code.
    
    ## Required behavior
    - While modal, keyboard focus stays inside the surface until it closes.
    - The surface remains until the user deliberately confirms or cancels the consequential action.
    
    ## States to cover
    - Decision closed with workspace intact
    - Initial deletion decision open
    - Decision closed after cancellation
    - Deletion decision reopened after cancellation
    - Deletion submitting
    - Decision closed after confirmed deletion
    - Deletion decision reopened after confirmation
    
    ## Accessibility
    - ARIA role: alertdialog[aria-modal=true]
    - The primary control or named region for Alert dialog has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    - Initial focus lands on the least destructive useful action unless reading long consequences first is safer.
    - Only an explicit decision or a documented safe cancellation closes the alert; no timer or accidental outside press dismisses it.
    - The alert dialog role, title, consequence, and both action names are announced when focus enters.
    - Tab moves only between decision controls
    - Escape cancels when cancellation remains safe
    - Enter activates the explicitly focused action
    
    ## When not to use
    - The action can be safely undone
    - The message only reports a result and needs no decision
    
    ## Acceptance criteria
    - The message names the exact consequence
    - Confirm and Cancel are explicit and visually distinct
    - Initial focus avoids accidental destructive confirmation
    - The alert cannot disappear before a decision
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    
    • @radix-ui/react-alert-dialog
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The need is tied to canonical behavior before any technical choice.
    • States, accessibility, and non-goals prevent a merely visual implementation.
    • Acceptance criteria and the output format make verification observable.

    Try next

    Verify Alert dialog on a real journey

    # Verify Alert dialog after implementation
    
    ## Objective
    Audit the Alert dialog implementation against its behavior, states, and accessibility requirements without changing it automatically.
    
    ## Checks
    - Replay the smallest representative journey.
    - Check keyboard behavior, focus, accessible name, and announcements.
    - Tie each gap to a specific acceptance criterion.
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    

    sha256:72fafc4dd706b0871459fcbba55cb7472d5f47e970d2bdeb16a4747999dd2db4

    Diagnose a problem

    Find and fix the Alert dialog defect

    # Debug Alert dialog in your agent
    
    ## Observed symptom
    [DESCRIBE THE SYMPTOM HERE]
    
    ## Observable checks
    - Reproduce the issue with the smallest relevant journey.
    - Compare behavior with the documented states and transitions for Alert dialog.
    - Verify keyboard behavior, focus, accessible name, and announcements.
    
    ## Possible causes
    - The chosen primitive does not match the expected behavior.
    - A state, transition, or focus return is missing.
    - A neighboring component captures an event or hides an accessible signal.
    
    ## Bounded corrections
    - Fix the reproduced cause without recreating neighboring components.
    - Preserve the public contract and add a focused regression test.
    - Do not install dependencies or change remote state without authorization.
    
    ## Final verification
    - The message names the exact consequence
    - Confirm and Cancel are explicit and visually distinct
    - Initial focus avoids accidental destructive confirmation
    - The alert cannot disappear before a decision
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    
    • @radix-ui/react-alert-dialog
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The explicit symptom prevents starting from an assumed fix.
    • Checks separate behavior, accessibility, and neighboring interference.
    • The fix stays bounded and must produce regression evidence.

    Try next

    Lock in the Alert dialog fix

    # Prevent the Alert dialog regression
    
    ## Objective
    Turn the reproduced cause into a focused regression test and compare Alert dialog with neighboring concepts before widening the fix.
    
    ## Checks
    - Prove that the test fails before the fix.
    - Prove that it passes after the bounded fix.
    - Verify that no neighboring component changed behavior.
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    

    sha256:77a44ac6148702d508fe8986ffcd4638979b4638cbdc6f75c7016a0ec3ac08ad

    Full entry, saving and provenance

    Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.

    Pack digest: sha256:104d6ae35bbfe300a70d2060002450e0c545a49cb2a766b66c05ff7603b1f172

    In code

    TechnologyPrimitiveVersionCaveat
    @radix-ui/react-alert-dialog

    AlertDialog.Root

    @radix-ui/react-alert-dialog@1.1.19Alert Dialog is for short consequential decisions; it does not make every confirmation flow appropriate.

    Technical details

    Behaviors

    • Contain focus

      While modal, keyboard focus stays inside the surface until it closes.

    • Require a decision

      The surface remains until the user deliberately confirms or cancels the consequential action.

    States

    • Decision closed with workspace intact

      Decision closed with workspace intact

    • Initial deletion decision open

      Initial deletion decision open

    • Decision closed after cancellation

      Decision closed after cancellation

    • Deletion decision reopened after cancellation

      Deletion decision reopened after cancellation

    • Deletion submitting

      Deletion submitting

    • Decision closed after confirmed deletion

      Decision closed after confirmed deletion

    • Deletion decision reopened after confirmation

      Deletion decision reopened after confirmation

    State transitions

    • Decision closed with workspace intact → Initial deletion decision open

      Delete workspace opens the warning and initially focuses the safer Keep it action.

    • Initial deletion decision open → Decision closed after cancellation

      Activating Keep it cancels deletion, closes the warning, and allows it to be reopened.

    • Initial deletion decision open → Decision closed with workspace intact

      Escape safely closes the warning before submission and returns focus without recording a confirmed result.

    • Decision closed after cancellation → Deletion decision reopened after cancellation

      Delete workspace reopens the same warning after a prior cancellation.

    • Deletion decision reopened after cancellation → Decision closed after cancellation

      Keep it or Escape closes the reopened warning and preserves the prior cancellation result.

    • Initial deletion decision open → Deletion submitting

      Delete permanently starts the simulated submission while the dialog stays open and both actions become disabled.

    • Deletion decision reopened after cancellation → Deletion submitting

      Delete permanently replaces the prior cancellation result with a new pending submission.

    • Deletion submitting → Decision closed after confirmed deletion

      When the simulated submission finishes, the dialog closes and the confirmed result is announced.

    • Decision closed after confirmed deletion → Deletion decision reopened after confirmation

      Delete workspace can reopen the replayable warning after the demonstration result is confirmed.

    • Deletion decision reopened after confirmation → Decision closed after confirmed deletion

      Escape closes the reopened warning and preserves the prior confirmed demonstration result.

    • Deletion decision reopened after confirmation → Decision closed after cancellation

      Keep it closes the reopened warning and changes the current demonstration result to cancelled.

    • Deletion decision reopened after confirmation → Deletion submitting

      Delete permanently starts another pending demonstration submission from the reopened warning.

    Test scenarios

    Context
    An administrator is about to permanently delete a workspace and all its shared links.
    Mission
    Open the warning, read the named consequence, cancel with the keyboard, then reopen and confirm deliberately.
    Primary state
    The warning names the workspace, explains permanent loss, and initially focuses the safer Keep it action.
    Edge case
    While deletion is submitting, both actions prevent duplicate activation and the dialog reports the pending state.

    Visual signals

    • Short warning message
    • Two clearly differentiated decisions
    • Consequential action named precisely

    Behavioral signals

    • Always modal
    • Does not disappear on a timer
    • Requires explicit confirmation or cancellation

    Accessibility

    Role
    alertdialog[aria-modal=true]
    Accessible name
    The primary control or named region for Alert dialog has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    Focus
    Initial focus lands on the least destructive useful action unless reading long consequences first is safer.
    Dismissal
    Only an explicit decision or a documented safe cancellation closes the alert; no timer or accidental outside press dismisses it.
    Scroll
    Background scrolling is locked while the modal is open. Overflow scrolls inside the surface and the focused control remains visible.
    Announcement
    The alert dialog role, title, consequence, and both action names are announced when focus enters.
    Keyboard
    • Tab moves only between decision controls
    • Escape cancels when cancellation remains safe
    • Enter activates the explicitly focused action

    Bindings

    Open the HTML, ARIA, Radix, and shadcn matrix
    • AlertDialog.Root

      implementationKind
      radix
      nativeElement
      Not applicable
      ariaPattern
      alertdialog
      radixPrimitive
      Alert Dialog
      shadcnRecipe
      Alert Dialog
      runtimeDependency
      @radix-ui/react-alert-dialog@1.1.19
      packageName
      @radix-ui/react-alert-dialog
      exportName
      AlertDialog.Root
      exactVersion
      1.1.19
      status
      verified
      sourceId
      source-ui-radix-alert-dialog
      deprecationStatus
      active
      replacement
      Not applicable
      validFrom
      Not applicable
      validUntil
      Not applicable

      Equivalence caveat: Alert Dialog is for short consequential decisions; it does not make every confirmation flow appropriate.

      Verify binding source

    Sources

    • WAI-ARIA APG: Alert and Message Dialogs
      sourceId
      source-ui-aria-alert-dialog
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-09T07:07:35Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:2e3579fd3125179dc0d744a9d49cd2ed9762d3bcc799a30bb6139bbf1eb96068
      status
      verified

      Claim covered: Alert dialog: informative APG guidance for the alert dialog pattern: roles, states, relationships, and keyboard interaction.

    • Radix Primitives: Alert Dialog
      sourceId
      source-ui-radix-alert-dialog
      kind
      documentation
      canonicalUrl
      https://www.radix-ui.com/primitives/docs/components/alert-dialog
      publisher
      Radix Primitives
      sourceRevision
      http-etag:W/"56b02ebbd00d292769cfc17e3da77458"
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:d1810fc5e715e04b4bb13f1a9f60788601c7ab79f4ecf770491dda92a6dd814b
      status
      verified

      Claim covered: Alert dialog: documented parts, state APIs, interaction behavior, and implementation limits for Radix Alert Dialog.

    • WAI-ARIA APG: Dialog Modal Pattern
      sourceId
      source-ui-aria-dialog-modal
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-09T07:07:35Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:4282d2eeb383c717ba41f52f0db1643fb3eb9acc33fa3879ef817e27c162453e
      status
      verified

      Claim covered: Alert dialog: informative APG guidance for the modal dialog pattern: roles, states, relationships, and keyboard interaction.

    • WAI-ARIA 1.2: Roles Model
      sourceId
      source-ui-wai-aria-roles
      kind
      standard
      canonicalUrl
      https://www.w3.org/TR/wai-aria-1.2/#roles
      publisher
      W3C WAI
      sourceRevision
      W3C-REC-wai-aria-1.2-20230606
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:c0fea16fc747779569ab754d2d25bca3e2b7e8a673b8ef5362aeb9ebc73a4849
      status
      verified

      Claim covered: Alert dialog: normative ARIA role definitions and constraints for the stated accessible role.

    • WCAG 2.2: Focus Appearance
      sourceId
      source-ui-wcag-understanding-focus-appearance
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-02T10:07:49Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:fdcf316a1f0e3cc758eda9618322d132862124ff0a3f3b1a3acbf20daf804ff0
      status
      verified

      Claim covered: Alert dialog: informative WCAG guidance for evaluating visible keyboard focus appearance.