XDS — Design System

AlertDialog@xds/core · XDSAlertDialog v0.0.13

Usage

AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes. For cases where you want to show an alert without managing open state, use the `useXDSImperativeAlertDialog` hook — call `alert.show(options)` and render `alert.element` in your tree.

ts
import {XDSAlertDialog} from '@xds/core/AlertDialog'

Best practices

Guidance	Practices
Do	Make the action button label specific — "Delete project" is better than "OK" or "Confirm".
Do	Describe what will happen in the description so the user knows the consequences before confirming.
Don't	Use AlertDialog for non-destructive actions — use a standard Dialog instead.

Sub-components

AlertDialog is a compound component with 2 sub-components.

XDSAlertDialog

A modal dialog that asks the user to confirm a destructive action.

Prop	Type	Description
isOpenrequired	boolean	Whether the dialog is open.
onOpenChangerequired	(isOpen: boolean) => unknown	Visibility change callback.
titlerequired	string	Dialog title. Linked via aria-labelledby.
descriptionrequired	string	Consequence description. Linked via aria-describedby.
actionLabelrequired	string	Action button label.
onActionrequired	() => unknown	Called when action button is clicked. Does NOT auto-close.
cancelLabel	string (default: 'Cancel')	Cancel button label.
actionVariant	XDSButtonVariant (default: 'destructive')	Action button variant.
isActionLoading	boolean	Shows loading spinner on the action button.
width	number \| string (default: 400)	Dialog width.
isInline	boolean (default: false)	Renders alert dialog content inline without modal behavior. For documentation previews and showcases only.

useXDSImperativeAlertDialog

Hook for showing an alert dialog without managing open state. Call alert.show(options) to open and alert.hide() to close. Render alert.element in your JSX tree.

Prop	Type	Description
show	(options: AlertDialogOptions) => void	Show the alert dialog with the given options. Options are the same as XDSAlertDialog props minus isOpen/onOpenChange.
hide	() => void	Hide the alert dialog.
isOpen	boolean	Whether the dialog is currently open.
element	ReactNode	The dialog element — render this in your JSX tree.

Examples

Common configurations, variations, and states.

AlertDialog — LoadingA confirmation dialog that shows a spinner while the action runs.

tsx
'use client';
import {useState} from 'react';
import {XDSAlertDialog} from '@xds/core/AlertDialog';
export default function AlertDialogAsyncAction() {
  const [isLoading, setIsLoading] = useState(false);
  return (
    <XDSAlertDialog
      isOpen
      isInline
      onOpenChange={() => {}}
      title="Revoke access?"
      description="This user will immediately lose access to all shared resources."
      actionLabel="Revoke"
      isActionLoading={isLoading}
      onAction={async () => {
        setIsLoading(true);
        await new Promise(r => setTimeout(r, 2000));
        setIsLoading(false);
      }}
    />
  );
}

Showcase source

tsx
'use client';
import {
  XDSAlertDialog,
  useXDSImperativeAlertDialog,
} from '@xds/core/AlertDialog';
// Remove isInline for production — alert dialogs should be modal.
export default function AlertDialogDeleteConfirmation() {
  const alert = useXDSImperativeAlertDialog();
  const alertProps = {
    title: 'Delete item?',
    description:
      'This action cannot be undone. The item and all its data will be permanently removed.',
    actionLabel: 'Delete',
  } as const;
  return (
    <>
      <XDSAlertDialog
        isOpen
        isInline
        onOpenChange={() => {}}
        {...alertProps}
        onAction={() =>
          alert.show({...alertProps, onAction: () => alert.hide()})
        }
      />
      {alert.element}
    </>
  );
}

Usage

import {XDSAlertDialog} from '@xds/core/AlertDialog'

Best practices

Guidance	Practices
Do	Make the action button label specific — "Delete project" is better than "OK" or "Confirm".
Do	Describe what will happen in the description so the user knows the consequences before confirming.
Don't	Use AlertDialog for non-destructive actions — use a standard Dialog instead.

Prop

Type

Description

isOpenrequired

boolean

Whether the dialog is open.

onOpenChangerequired

(isOpen: boolean) => unknown

Visibility change callback.

titlerequired

string

Dialog title. Linked via aria-labelledby.

descriptionrequired

string

Consequence description. Linked via aria-describedby.

actionLabelrequired

string

Action button label.

onActionrequired

() => unknown

Called when action button is clicked. Does NOT auto-close.

cancelLabel

string (default: 'Cancel')

Cancel button label.

actionVariant

XDSButtonVariant (default: 'destructive')

Action button variant.

isActionLoading

boolean

Shows loading spinner on the action button.

width

number | string (default: 400)

Dialog width.

isInline

boolean (default: false)

Renders alert dialog content inline without modal behavior. For documentation previews and showcases only.

Prop

Type

Description

show

(options: AlertDialogOptions) => void

Show the alert dialog with the given options. Options are the same as XDSAlertDialog props minus isOpen/onOpenChange.

hide

() => void

Hide the alert dialog.

isOpen

boolean

Whether the dialog is currently open.

element

ReactNode

The dialog element — render this in your JSX tree.

tsx

'use client'; import {useState} from 'react'; import {XDSAlertDialog} from '@xds/core/AlertDialog'; export default function AlertDialogAsyncAction() { const [isLoading, setIsLoading] = useState(false); return ( <XDSAlertDialog isOpen isInline onOpenChange={() => {}} title="Revoke access?" description="This user will immediately lose access to all shared resources." actionLabel="Revoke" isActionLoading={isLoading} onAction={async () => { setIsLoading(true); await new Promise(r => setTimeout(r, 2000)); setIsLoading(false); }} /> ); }

tsx

'use client'; import { XDSAlertDialog, useXDSImperativeAlertDialog, } from '@xds/core/AlertDialog'; // Remove isInline for production — alert dialogs should be modal. export default function AlertDialogDeleteConfirmation() { const alert = useXDSImperativeAlertDialog(); const alertProps = { title: 'Delete item?', description: 'This action cannot be undone. The item and all its data will be permanently removed.', actionLabel: 'Delete', } as const; return ( <> <XDSAlertDialog isOpen isInline onOpenChange={() => {}} {...alertProps} onAction={() => alert.show({...alertProps, onAction: () => alert.hide()}) } /> {alert.element} </> ); }