Dialog - Web (AI Kit)

For development, import Dialog from @servicetitan/anvil2-ai-kit. For design, find it in the AI Kit Web Component Library file.

Options

The Dialog supports a primary action, an optional secondary action, and a danger variant for destructive confirmations.

Actions

Omit secondaryAction for a single-action, acknowledge-only dialog — the lone action sits at the trailing edge of the footer. Pass both for a confirm/cancel pair, as in the hero example above.

Action Variants

Primary Action

primaryAction defaults to variant: "primary", rendering the standard confirm treatment.

Danger Action

Set primaryAction’s variant to "danger" for a destructive confirmation — it renders the critical (red) Button so the risk of the action is visually distinct.

No Actions

Omit both primaryAction and secondaryAction for a footerless dialog — useful for a media preview or informational dialog where the header’s X close button is the only dismiss affordance.

Behavior

The Dialog traps focus while open and scrolls its own body independently of the pinned header and footer.

Scrolling Body

Body content beyond 90% of the viewport height scrolls within the dialog while the header and footer stay pinned.

Usage Guidelines

When to Use

Use the Dialog when:

Confirming a decision before continuing – The user must confirm or cancel, such as leaving a page with unsaved changes. Pair a primary action with a secondary action.
Confirming a destructive action – The action deletes data or can’t be undone. Use the danger primary action so the risk is visually distinct.
Acknowledging a message – The user only needs to read the content and dismiss it. Use a single primary action.
Previewing media or information – Content such as an attachment preview needs a focused view with no footer actions. The header close button dismisses it.

When not to use

Avoid using the Dialog for:

Presenting forms, lists, or composed layouts – Dialog content is message-style: text, phrasing content, or rendered Markdown. Use the Bottom Sheet instead.
Asking a clarifying question before the agent continues – Use the Agent Prompt instead, which asks inline in place of the Prompt Bar.

Keyboard Interaction

Users can navigate, scroll, and dismiss the Dialog using standard keyboard controls.

Key	Description
Tab	Moves focus among the close button, body content, and footer actions
Enter / Space	Activates the focused close button or footer action
Escape	Dismisses the dialog

Code

Implementation
Dialog Props

Common Examples

To use the Dialog, pass the required title and content props. Open it with a Carto Button through trigger, or control it with isOpen and onOpenChange.

import { Button, Dialog } from "@servicetitan/anvil2-ai-kit";

function ExampleComponent() {
  return (
    <Dialog
      title="Leave without saving?"
      trigger={<Button label="Leave page" />}
      content="Your changes haven't been saved."
      primaryAction={{ label: "Leave" }}
      secondaryAction={{ label: "Stay" }}
    />
  );
}

Actions

Pass primaryAction for the confirm action and secondaryAction for dismissal. The dialog fixes both buttons at medium size and fixes the secondary action to the secondary variant.Use variant: "danger" on primaryAction for destructive confirmation.

Footerless

Omit both actions for a footerless dialog. The header close button remains available.

Controlled state

Omit trigger and pass isOpen with onOpenChange when an event or another component opens the dialog. Footer actions request closure after their own onPress handlers run. For asynchronous flows that must remain open, treat onOpenChange as a request and retain control of isOpen.

<Dialog
  title="Rename"
  isOpen={isOpen}
  onOpenChange={setOpen}
  content={<Text text="Choose a new name." />}
  primaryAction={{ label: "Save", onPress: save }}
  secondaryAction={{ label: "Cancel" }}
/>

Scrolling body

Content beyond 90vh scrolls inside the body while the header and footer remain visible.

Internationalization

Localize title, content, and action labels before passing them to Dialog.

The built-in header close button currently uses the English accessible label "Close".

React Accessibility

The required title labels the modal through aria-labelledby.
React Aria supplies focus trapping and restoration, scroll lock, aria-modal, Escape dismissal, and outside-interaction dismissal.
The body is always keyboard-focusable so keyboard users can scroll plain text.
Set isKeyboardDismissDisabled only when the flow requires blocking Escape.

<Dialog
  title="Delete project?"
  content="This action cannot be undone."
  trigger={<Button label="Delete project" variant="danger" />}
  primaryAction={{ label: "Delete", variant: "danger" }}
  secondaryAction={{ label: "Cancel" }}
/>

`Dialog` Props

The Dialog accepts the following props and forwards remaining React Aria ModalOverlay state and dismissal props.

ReactNode

required

Message-style body content. Pass text, phrasing content, or rendered Markdown, not arbitrary page layout.

string

required

Accessible title rendered in the header.

string

Class merged onto the dialog surface.

boolean

Whether the dialog starts open when uncontrolled.

boolean

default:"true"

Whether outside interaction closes the dialog.

boolean

Prevents Escape from closing the dialog.

boolean

Controlled open state. Pair with onOpenChange.

(isOpen: boolean) => void

Called when the open state changes.

DialogPrimaryAction

Confirm action. Accepts Button props except size; supports variant="primary" (default) or variant="danger".

Omit<ButtonProps, 'size' | 'variant'>

Optional dismiss action. Always renders at medium size with the secondary variant.

ReactElement<ButtonProps>

Carto Button that opens the dialog. Omit for controlled state.

Concepts & Guidelines

Anvil2

Resources

Dialog - Web (AI Kit)

Options

Actions

Action Variants

Primary Action

Danger Action

No Actions

Behavior

Scrolling Body

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Code

Common Examples

Actions

Footerless

Controlled state

Scrolling body

Internationalization

React Accessibility

`Dialog` Props

​Options

​Actions

​Action Variants

​Primary Action

​Danger Action

​No Actions

​Behavior

​Scrolling Body

​Usage Guidelines

​When to Use

​When not to use

​Keyboard Interaction

​Code

​Common Examples

​Actions

​Footerless

​Controlled state

​Scrolling body

​Internationalization

​React Accessibility

​Dialog Props

Options

Actions

Action Variants

Primary Action

Danger Action

No Actions

Behavior

Scrolling Body

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Code

Common Examples

Actions

Footerless

Controlled state

Scrolling body

Internationalization

React Accessibility

`Dialog` Props