Skip to main content

Starwind UI v3.0 is now available! Migration guide

On this page

Alert Dialog Primitive

View Markdown

Alert Dialog is a Starwind Runtime primitive in the dialog-native-overlay contract family. Astro, React, Vue, and Svelte components use the same underlying interactions. Each framework has its own way to read and update state. See the examples and your installed package’s types for the available props and events. Plain HTML uses DOM events and Runtime methods.

Anatomy

Use the Astro primitive adapter to render AlertDialog anatomy with the Runtime wiring included.

---
import { AlertDialog } from "@starwind-ui/astro/alert-dialog";
---


<AlertDialog.Root>
  <AlertDialog.Trigger>Delete item</AlertDialog.Trigger>
  <AlertDialog.Backdrop />
  <AlertDialog.Viewport>
    <AlertDialog.Popup>
      <AlertDialog.Title>Delete item?</AlertDialog.Title>
      <AlertDialog.Description>This action cannot be undone.</AlertDialog.Description>
      <AlertDialog.Close>Cancel</AlertDialog.Close>
    </AlertDialog.Popup>
  </AlertDialog.Viewport>
</AlertDialog.Root>

API Reference

Root

The main element that owns the Alert Dialog Runtime instance.

Default element
div
Discovery hook
data-sw-alert-dialog
Role
-

Props

Prop Type Default Toggle
open boolean -
Description
Controls whether Alert Dialog is open.
Kind
control
Targets
root
Full type
boolean
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
defaultOpen boolean false
Description
Sets whether Alert Dialog starts open.
Kind
control
Targets
root
Full type
boolean
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
closeOnEscape boolean true
Description
Closes Alert Dialog when Escape is pressed.
Kind
option
Targets
-
Full type
boolean
closeOnOutsideInteract boolean false
Description
Closes Alert Dialog when the user interacts outside it.
Kind
option
Targets
-
Full type
boolean
modal boolean true
Description
Makes Alert Dialog behave as a modal overlay.
Kind
option
Targets
-
Full type
boolean
onCloseComplete (open: boolean, details: AlertDialogCloseCompleteDetails) => void -
Description
Runs after Alert Dialog has finished closing.
Kind
callback
Targets
-
Full type
(open: boolean, details: AlertDialogCloseCompleteDetails) => void
onOpenChange (open: boolean, details: AlertDialogOpenChangeDetails) => void -
Description
Runs when Alert Dialog opens or closes.
Kind
callback
Targets
-
Full type
(open: boolean, details: AlertDialogOpenChangeDetails) => void
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen

Events

Event Callback Value Toggle
closeComplete onCloseComplete open: boolean
Description
Fires after Alert Dialog has finished closing.
DOM event
starwind:close-complete
Details type
AlertDialogCloseCompleteDetails
Timing
after-state-commit
Cancelable
No
openChange onOpenChange open: boolean
Description
Fires when Alert Dialog opens or closes.
DOM event
starwind:open-change
Details type
AlertDialogOpenChangeDetails
Timing
before-state-commit
Cancelable
Yes
Cancellation sequence
  1. Check internal eligibility and intent.
  2. Create one details object for the proposal.
  3. Call the Runtime callback with the details object when the controller exposes one.
  4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
  5. Read details.isCanceled, including cancellation caused by preventDefault().
  6. Apply the accepted state.
  7. Notify Runtime subscribers and other accepted-only observers.

State

State Type Props Toggle
open boolean open / defaultOpen
Description
Tracks whether Alert Dialog is open.
Initial attribute
data-default-open
Runtime getter
getOpen
Runtime setter
setOpen
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog - Marks the Root part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Root part.
Metadata
Attribute Value Description
data-default-open - Reflects the default open prop on the Root part.
data-close-on-escape - Reflects the close on escape prop on the Root part.
data-close-on-outside-interact - Reflects the close on outside interact prop on the Root part.
data-modal - Reflects the modal prop on the Root part.

Trigger

The control that opens, closes, or targets the Alert Dialog content.

Default element
button
Discovery hook
data-sw-alert-dialog-trigger
Role
-

Props

Prop Type Default Toggle
asChild boolean false
Description
Merges behavior onto your child element instead of rendering the default Trigger element.
Kind
rendering
Targets
trigger, close
Full type
boolean
targetId string -
Description
Targets a specific root element by id.
Kind
attribute
Targets
trigger
Full type
string

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog-trigger - Marks the Trigger part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Trigger part.
Metadata
Attribute Value Description
data-sw-alert-dialog-target-id - Reflects the sw alert dialog target id prop on the Trigger part.

Portal

Moves Alert Dialog overlay content to the document body when needed.

Default element
div
Discovery hook
data-sw-alert-dialog-portal
Role
-

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog-portal - Marks the Portal part so Starwind Runtime can find it.
data-placement - Marks the Portal part so Starwind Runtime can find it.
Metadata
Attribute Value Description
data-container - Reflects the container prop on the Portal part.
data-disabled - Reflects the disabled prop on the Portal part.
data-sw-portal-placement runtime Identifies Portal metadata for styling and selectors.

Backdrop

The backdrop shown behind the Alert Dialog overlay.

Default element
div
Discovery hook
data-sw-alert-dialog-backdrop
Role
-

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog-backdrop - Marks the Backdrop part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Backdrop part.

Viewport

The visible viewport for Alert Dialog content.

Default element
div
Discovery hook
data-sw-alert-dialog-viewport
Role
-

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog-viewport - Marks the Viewport part so Starwind Runtime can find it.

Popup

The floating content container for Alert Dialog.

Default element
dialog
Discovery hook
data-sw-alert-dialog-popup
Role
alertdialog

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog-popup - Marks the Popup part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Popup part.

Title

The accessible title for Alert Dialog.

Default element
h2
Discovery hook
data-sw-alert-dialog-title
Role
-

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog-title - Marks the Title part so Starwind Runtime can find it.

Description

Supporting description text for Alert Dialog.

Default element
p
Discovery hook
data-sw-alert-dialog-description
Role
-

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog-description - Marks the Description part so Starwind Runtime can find it.

Close

A control that closes Alert Dialog.

Default element
button
Discovery hook
data-sw-alert-dialog-close
Role
-

Props

Prop Type Default Toggle
asChild boolean false
Description
Merges behavior onto your child element instead of rendering the default Close element.
Kind
rendering
Targets
trigger, close
Full type
boolean

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-alert-dialog-close - Marks the Close part so Starwind Runtime can find it.

Runtime API

Factory
createAlertDialog
Import
@starwind-ui/runtime/alert-dialog
Root hook
root data-sw-alert-dialog
Option props
closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open

Option Lifecycles

OptionLifecycle
closeOnEscapeconstructor-only
closeOnOutsideInteractconstructor-only
defaultOpenconstructor-only
modalconstructor-only
onCloseCompleteconstructor-only
onOpenChangeconstructor-only
opensetter-backed

Runtime Setters

Method Target Description
setOpen state: open Opens or closes Alert Dialog from Runtime code.

Related Styled Components

Component Relationship
Alert Dialog Direct primitive

Changelog

View version history v1.2.0 6 releases

v1.2.0

  • Vue Alert Dialog keeps its current open state when a change is canceled and responds to later open or close requests from your app.
  • Trigger, action, and cancel buttons added after the dialog mounts now work without reopening it.
  • Reduced background work when a React page uses multiple menus, tooltips, or other portals.
  • Added `asChild` support to React and Vue controls so you can use your own elements without an extra wrapper.
  • Fixed nested Svelte overlays inside a dialog appearing behind their parent or failing to receive clicks.
  • Reduced background work when a Vue page uses multiple menus, tooltips, or other portals.
  • Fixed nested overlays appearing behind their parent in Vue and Svelte. Overlays can now render under the document body; if custom CSS or DOM queries require them to stay inside a parent, set a portal container or add `data-floating-root` to that parent.
  • Fixed React 18 retaining removed popup elements when the parent component stays mounted.
  • Updated the shared setup file included with the Astro Primitive. Its public API and behavior are unchanged.

v1.1.1

  • Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.

v1.1.0

  • Added portable Portal container and disabled controls, with deterministic framework and Runtime placement reporting for nested floating content.

v1.0.0

  • Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.

v0.1.1

  • Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
  • Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.

v0.1.0

  • Introduced modal confirmation state with focus management, dismissal rules, and accessible alert-dialog semantics.