Alert Dialog

A modal dialog that interrupts the user with important content and expects a response.

import { component$, useStyles$ } from '@builder.io/qwik';
import { AlertDialog } from 'qwik-primitives';
import styles from './styles.css?inline';

export const AlertDialogDemo = component$(() => {
  useStyles$(styles);

  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger class="alert-dialog-trigger">Revoke access</AlertDialog.Trigger>
      <AlertDialog.Content class="alert-dialog-content">
        <AlertDialog.Title class="alert-dialog-title">Revoke access</AlertDialog.Title>
        <AlertDialog.Description class="alert-dialog-description">
          Are you sure? This application will no longer be accessible and any existing sessions will be expired.
        </AlertDialog.Description>
        <div class="alert-dialog-footer">
          <AlertDialog.Cancel class="alert-dialog-cancel">Cancel</AlertDialog.Cancel>
          <AlertDialog.Action class="alert-dialog-action">Revoke access</AlertDialog.Action>
        </div>
      </AlertDialog.Content>
    </AlertDialog.Root>
  );
});

Features

  • Focus is automatically trapped.
  • Can be controlled or uncontrolled.
  • Manages screen reader announcements with Title and Description components.
  • Esc closes the component automatically.
  • Adheres to the Alert Dialog WAI-ARIA design pattern.

Import

import { AlertDialog } from 'qwik-primitives';

Anatomy

Import all parts and piece them together.

import { component$ } from '@builder.io/qwik';
import { AlertDialog } from 'qwik-primitives';

export const AlertDialogDemo = component$(() => {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger />
      <AlertDialog.Content>
        <AlertDialog.Title />
        <AlertDialog.Description />
        <AlertDialog.Cancel />
        <AlertDialog.Action />
      </AlertDialog.Content>
    </AlertDialog.Root>
  );
});

API Reference

Root

Contains all the parts of an alert dialog.

Props

defaultOpen
Description

The open state of the alert dialog when it is initially rendered. Use when you do not need to control its open state.

Type
boolean
Default
No default value
open
Description

The controlled open state of the alert dialog. Must be used in conjunction with onOpenChange$.

Type
Signal
Default
No default value
onOpenChange$
Description

Event handler called when the open state of the alert dialog changes.

Type
QRL
Default
No default value

Trigger

The button that opens the alert dialog. This component is based on the button element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
disabled
Description

When true, prevents the user from interacting with the trigger.

Type
boolean
Default
No default value
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"alert-dialog"
[data-part]
Values
"trigger"
[data-state]
Values
"open" | "closed"
[data-disabled]
Values

Present when disabled

Content

Contains content to be rendered when the alert dialog is open. This component is based on the dialog element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
loop
Description

When true, press Tab from last focusable element will focus first focusable element and Shift + Tab from first focusable element will focus last focusable element.

Type
boolean
Default
true
autoFocus
Description

By default, when the component is opened, focus is programmatically moved to AlertDialog.Cancel to anticipate a response to the prompt. When AlertDialog.Cancel not exist or is disabled the focus will be move focus on the first focusable element. To specify the element that should receive initial focus, adddata-qwik-primitives-auto-focus attribute on this element.

Type
boolean
Default
true
restoreFocus
Description

Whether to restore focus back to the AlertDialog.Trigger when the alert dialog is closed.

Type
boolean
Default
true
preventScroll
Description

Whether to prevent scrolling behind the alert dialog when it's opened.

Type
boolean
Default
true
closeOnBackPress
Description

Whether to close the alert dialog when the back is press on mobile devices.

Type
boolean
Default
true
closeOnEscapeKeyDown
Description

Whether to close the alert dialog when the escape key is down.

Type
boolean
Default
true
closeOnClickOutside
Description

Whether to close the alert dialog when the outside is clicked.

Type
boolean
Default
No default value
onEscapeKeyDown$
Description

Event handler called when the escape key is down.

Type
QRL
Default
No default value
onClickOutside$
Description

Event handler called when a pointer event occurs outside the bounds of the component.

Type
QRL
Default
No default value
onOpen$
Description

Event handler called when the content is fully open. If you animate the content when it opens this event handler was call after animation end.

Type
QRL
Default
No default value
onClose$
Description

Event handler called when the content is fully close. If you animate the content when it closes this event handler was call after animation end.

Type
QRL
Default
No default value
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"alert-dialog"
[data-part]
Values
"content"
[data-state]
Values
"open" | "closed"

Cancel

A button that closes the alert dialog. This button should be distinguished visually from AlertDialog.Action buttons. This component is based on the button element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
disabled
Description

When true, prevents the user from interacting with the component.

Type
boolean
Default
No default value
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"alert-dialog"
[data-part]
Values
"cancel"
[data-disabled]
Values

Present when disabled

Action

A button that closes the alert dialog. These buttons should be distinguished visually from the AlertDialog.Cancel button. This component is based on the button element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
disabled
Description

When true, prevents the user from interacting with the component.

Type
boolean
Default
No default value
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"alert-dialog"
[data-part]
Values
"action"
[data-disabled]
Values

Present when disabled

Title

An accessible title to be announced when the alert dialog is opened. This component is based on the h2 element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
level
Description

The level of the title, determines which tag will be used (h1-h6).

Type
enum
Default
"2"
visuallyHidden
Description

When true, title will be hide from the screen in an accessible way.

Type
boolean
Default
No default value
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"alert-dialog"
[data-part]
Values
"title"
[data-level]
Values
"1" | "2" | "3" | "4" | "5" | "6"

Description

An accessible description to be announced when the alert dialog is opened. This component is based on the p element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
visuallyHidden
Description

When true, description will be hide from the screen in an accessible way.

Type
boolean
Default
No default value
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"alert-dialog"
[data-part]
Values
"description"

Examples

Initially open

The AlertDialog.Content component is based on HTML dialog element. Opening or closing this component is only possible in the browser. There is no way to do it on the server side. For this reason, to get the effect of an initially opened Alert dialog, you need to use useVisibleTask$.

import { component$, useSignal, useVisibleTask$ } from '@builder.io/qwik';
import { AlertDialog } from 'qwik-primitives';

export const AlertDialogDemo = component$(() => {
  const isOpen = useSignal(false);

  // eslint-disable-next-line qwik/no-use-visible-task
  useVisibleTask$(
    () => {
      isOpen.value = true;
    },
    { strategy: 'document-ready' }
  );

  return (
    <AlertDialog.Root open={isOpen} onOpenChange$={() => (isOpen.value = !isOpen.value)}>
      <AlertDialog.Trigger>Open alert dialog</AlertDialog.Trigger>
      <AlertDialog.Content>
        <AlertDialog.Title>Alert dialog title</AlertDialog.Title>
        <AlertDialog.Description>Alert dialog description</AlertDialog.Description>
        <AlertDialog.Cancel>Alert dialog cancel</AlertDialog.Cancel>
        <AlertDialog.Action>Alert dialog action</AlertDialog.Action>
      </AlertDialog.Content>
    </AlertDialog.Root>
  );
});

Initial focus

By default, when the component is opened, focus is programmatically moved to AlertDialog.Cancel to anticipate a response to the prompt. When AlertDialog.Cancel not exist or is disabled the focus will be move focus on the first focusable element. To specify the element that should receive initial focus, add data-qwik-primitives-auto-focus attribute on this element.

import { component$ } from '@builder.io/qwik';
import { AlertDialog } from 'qwik-primitives';

export const AlertDialogDemo = component$(() => {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger>Open alert dialog</AlertDialog.Trigger>
      <AlertDialog.Content>
        <AlertDialog.Title>Alert dialog title</AlertDialog.Title>
        <AlertDialog.Description>Alert dialog description</AlertDialog.Description>

        <label for="first-input">First input</label>
        <input id="first-input" type="text" placeholder="First input" />

        <label for="second-input">Second input (will have initial focus)</label>
        <input
          data-qwik-primitives-auto-focus=""
          id="second-input"
          type="text"
          placeholder="Second input (will have initial focus)"
        />

        <label for="third-input">Third input</label>
        <input id="third-input" type="text" placeholder="Third input" />

        <AlertDialog.Cancel>Alert dialog cancel</AlertDialog.Cancel>
        <AlertDialog.Action>Alert dialog action</AlertDialog.Action>
      </AlertDialog.Content>
    </AlertDialog.Root>
  );
});

Restore focus

By default, focus will be restore back to the AlertDialog.Trigger when the alert dialog is closed. To specify the element that should receive focus after close alert dialog pass restoreFocus={false} on AlertDialog.Content component. You must also implement how you want and witch element should recive focus after deativate. Below you have example implementation.

import { component$, useSignal, $ } from '@builder.io/qwik';
import { AlertDialog } from 'qwik-primitives';

export const AlertDialogDemo = component$(() => {
  const restoreFocusElementRef = useSignal<HTMLButtonElement | undefined>(undefined);

  const handleClose$ = $(() => {
    // Using `setTimeout` is required, without it the element will not receive focus.
    setTimeout(() => {
      if (restoreFocusElementRef.value) {
        restoreFocusElementRef.value.focus();
      }
    });
  });

  return (
    <>
      <button ref={restoreFocusElementRef} type="button">
        Button (focus will be move on this element after close dialog)
      </button>

      <AlertDialog.Root>
        <AlertDialog.Trigger>Open alert dialog</AlertDialog.Trigger>
        <AlertDialog.Content restoreFocus={false} onClose$={handleClose$}>
          <AlertDialog.Title>Alert dialog title</AlertDialog.Title>
          <AlertDialog.Description>Alert dialog description</AlertDialog.Description>
          <AlertDialog.Cancel>Alert dialog cancel</AlertDialog.Cancel>
          <AlertDialog.Action>Alert dialog action</AlertDialog.Action>
        </AlertDialog.Content>
      </AlertDialog.Root>
    </>
  );
});

Animations

Use data-state attribute to provide animations for the AlertDialog.Content component when alert dialog it opens/closes.

import { component$, useStyles$ } from '@builder.io/qwik';
import { AlertDialog } from 'qwik-primitives';
import styles from './styles.css?inline';

export const AlertDialogDemo = component$(() => {
  useStyles$(styles);

  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger>Open alert dialog</AlertDialog.Trigger>
      <AlertDialog.Content class="alert-dialog-content">
        <AlertDialog.Title>Alert dialog title</AlertDialog.Title>
        <AlertDialog.Description>Alert dialog description</AlertDialog.Description>
        <AlertDialog.Cancel>Alert dialog cancel</AlertDialog.Cancel>
        <AlertDialog.Action>Alert dialog action</AlertDialog.Action>
      </AlertDialog.Content>
    </AlertDialog.Root>
  );
});

Style the overlay

Use the ::backdrop CSS pseudo-element to style AlertDialog.Content component overlay. The overlay can also be animated. Firefox currently does not support backdrop animations. The fallback for browsers that do not support animated backdrops is the same as a non-animated backdrop.

import { component$, useStyles$ } from '@builder.io/qwik';
import { AlertDialog } from 'qwik-primitives';
import styles from './styles.css?inline';

export const AlertDialogDemo = component$(() => {
  useStyles$(styles);

  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger>Open alert dialog</AlertDialog.Trigger>
      <AlertDialog.Content class="alert-dialog-content">
        <AlertDialog.Title>Alert dialog title</AlertDialog.Title>
        <AlertDialog.Description>Alert dialog description</AlertDialog.Description>
        <AlertDialog.Cancel>Alert dialog cancel</AlertDialog.Cancel>
        <AlertDialog.Action>Alert dialog action</AlertDialog.Action>
      </AlertDialog.Content>
    </AlertDialog.Root>
  );
});

Accessibility

Adheres to the Alert Dialog WAI-ARIA design pattern.

Keyboard Interactions

Space
Description

Opens/closes the alert dialog.

Enter
Description

Opens/closes the alert dialog.

Tab
Description

Moves focus to the next focusable element.

Shift + Tab
Description

Moves focus to the previous focusable element.

Esc
Description

Closes the alert dialog and moves focus to AlertDialog.Trigger.