Dialog - Web

For development, import Dialog from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Dialog consists of five primary elements that work together to temporarily block interactions within the main view.

Header
Body content
Backdrop
Close action
Footer actions

Options

The Dialog supports flexible content, footer actions, and sizing configurations to accommodate various modal scenarios.

Body content

Add any type of content into the body of a Dialog.

Sizing

The Dialog has 4 sizing options: medium (default), large, extra large, and fullscreen.

Default

Large

Extra Large

Fullscreen

Sizing table

Sizing	Width	Height	Max Height
Medium (default)	22.5rem / 360px	auto	100% - (1rem * 2)
Large	35rem / 560px	auto	100% - (1rem * 2)
Extra Large	70rem / 1120px	auto	100% - (1rem * 2)
Fullscreen	100%	100%	–

Behavior

The Dialog responds to content overflow and scrolling requirements while maintaining focus management.

Overflow handling

Content in the Dialog will wrap, rather than truncate. Header content will avoid colliding with the close action, while footer actions will wrap to the right, with the right-most actions being at the bottom. Footer actions can have a custom overflow behavior if needed.

Scrolling

The body region of the Dialog will scroll when space is not available. The Dialog’s height will fill the height of the browser window (minus 1 rem top and bottom margins), and scroll past that point.

Usage Guidelines

Standard	Requirement
DoFocus on important tasks	Use Dialogs to bring focus to important tasks. Situations that require user action before continuing, confirmations, and quick, infrequent tasks are among the most common use cases.
DoConfirm important actions	Use Dialogs to confirm important, higher-risk actions. Destructive, hard to reverse decisions particularly benefit from Dialog usage. Not all actions require a confirmation; use only as needed.
DoMulti-step footer navigation	For Dialogs with multiple steps, use the recommended footer arrangement for navigation, adjusting the final step’s primary action copy as needed; see Multi-step Dialogs.
DoForms in Dialogs	Keep small Dialog forms short, using multi-step when needed; fullscreen Dialogs may use forms as complex as an ordinary page; see Forms in Dialogs.
DoStack a Dialog with a fullscreen Dialog	Since a fullscreen Dialog mimics a standard page, stack a smaller Dialog as needed; see Stacking a Dialog with a fullscreen Dialog.
Don’tOveruse Dialogs	Dialogs are interruptive UIs by design and may disorient users when used mid-flow. It is easy to overuse Dialogs in flows, particularly in complex UIs — reduce usage to only what is needed and find alternatives to surface information on the page. Overuse restricts a user’s ability to perform other tasks, blocks other content on the screen, can be difficult to find and relocate, is difficult to directly link to, and adds additional interaction steps to open and close.
Don’tCommunicate errors	Using a Dialog to convey errors is an anti-pattern. It requires a user to actively remember its contents once the Dialog is closed. See the error pattern for alternatives.
Don’tStacking smaller Dialogs	Avoid stacking smaller Dialogs together; see Avoid stacking smaller Dialogs together.

Alternatives

Dialog vs Alert

Dialogs are interruptive by design, while an Alert is non-disruptive. Prefer using an Alert when information needs to be conveyed, only using a Dialog when there is a clear need to interrupt a flow, such as a confirmation of destructive or irreversible actions.

Dialog vs Drawer

	Dialog	Drawer
Complete a secondary task	Simple, one step tasks	1-3 steps at most. Tasks with more steps should be on a separate page
Display additional information related to the context in the main page	Yes, ideal for short content	Yes, ideal for longer, more complex information
Confirm user actions	Yes	No

Both Dialogs and Popovers overlay elements on the page. Dialogs are preferable when a situation requires user attention and for more complicated flows.

	Popover	Dialog
Content allowed in the container?	Any content	Any content
Complexity of content?	From simple to a few interactions	From simple to high complex
Backdrop applied to page?	No	Yes

How to Use

Multi-step Dialogs

Dialogs of all sizes may involve multiple steps. We recommend using the footer arrangement shown for user navigation. Adjust the final step’s primary action copy as needed.

Forms in Dialogs

A form can exist within a Dialog. Beyond the standard usage guidance to Forms, small Dialogs should especially keep form length low, and make use of multi-steps when needed. Fullscreen Dialogs may use forms as complex as an ordinary page.

Avoid stacking smaller Dialogs together

Don’t

Stacking a Dialog with a fullscreen Dialog

Since a fullscreen Dialog mimics a standard page, stack a smaller Dialog as needed.

Content

Content within the Dialog should be concise, actionable, and clearly communicate the task or information.

Write titles as verbs

Titles should have a clear verb + noun question or statement.

Don’t

Make body content concise and actionable

Use imperative verbs when telling users what they need to know or do. Don’t use permissive language like “you can”.

Don’t

Buttons should be clear, predictable, and action-oriented

Users should be able to predict what will happen when they click a button. Lead with a strong verb that encourages action. Use a verb/noun pair on actions in most cases. Common actions like Save, Close, or Cancel do not require an accompanying noun.

Don’t

Keyboard Interaction

Users can navigate the Dialog using standard keyboard controls.

Key	Interaction
Tab	Cycles through tab-able elements within the Dialog
Escape	Closes the Dialog

Accessibility

Focus management

There are a few different things to keep in mind with the Dialog’s focus / keyboard behavior.

Trap focus within the Dialog

By default, the Dialog will trap focus within itself. Elements outside of the Dialog would not be accessible by keyboard, unless another element itself took the focus.

First focus management

What element the Dialog focuses on open is dependent on a few factors:

If the body content has a focus-able element, the Dialog will focus on the first of these elements.
If the body does not have have an element, then the following is the preferred first-focus element:
- With no actions at all, focus first on the close action.
- When a primary action exists, focus first on the primary action.
- When a primary destructive action exists, focus first on the secondary cancel action.

Return focus on close

When a Dialog is closed and the original context that triggered the Dialog is still present, focus should return to the element that triggered the Dialog. For more guidance on focus management with dynamic content, see changing content best practices.

Code

Common Examples

import { Button, Dialog, Flex } from "@servicetitan/anvil2";
import { useState } from "react";

function ExampleComponent() {
  const [isOpen, setIsOpen] = useState(true);
  return (
    <Dialog open={isOpen} onClose={() => setIsOpen(false)}>
      <Dialog.Header>Dialog Header</Dialog.Header>
      <Dialog.Content>This is the dialog body content.</Dialog.Content>
      <Dialog.Footer>
        <Flex gap="3" justifyContent="flex-end">
          <Dialog.CancelButton>Cancel</Dialog.CancelButton>
          <Button appearance="primary">Continue</Button>
        </Flex>
      </Dialog.Footer>
    </Dialog>
  );
}

Opening dialogs

Dialogs should be shown and hidden using the open prop, rather than conditionally rendering the entire component.This allows us to follow the HTML standard for dialog elements, which is what we render under-the-hood. This also prevents some other issues, such as skipping the exit animation or missing toast messages.

<Dialog open={shouldBeOpen} {...otherProps} />

{
  shouldBeOpen && <Dialog {...otherProps} />;
}

Don’t

Rendering content on open

By default, dialog content is rendered on page load, but hidden until the dialog is opened. In some cases, such as making heavy API calls or with content that may require large re-renders based on other user actions, it could be advantageous to wait to render the dialog content.To render dialog content only when it is opened, conditionally render the children based on the state used in the Dialog.open prop.

import { Dialog, Flex, TextField } from "@servicetitan/anvil2";
import { useState } from "react";

function ExampleComponent() {
  const [isOpen, setIsOpen] = useState(true);
  return (
    <Dialog open={isOpen} onClose={() => setIsOpen(false)}>
      {isOpen && (
        <Dialog.Header>Dialog Header</Dialog.Header>
        <Dialog.Content>
          <ComponentWithHeavyAPICalls />
        </Dialog.Content>
        <Dialog.Footer>
          <Flex gap="3" justifyContent="flex-end">
            <Dialog.CancelButton>
              Cancel
            </Dialog.CancelButton>
          </Flex>
        </Dialog.Footer>
      )}
    </Dialog>
  )
}

Sticky Content

Use the sticky prop on Dialog.Content to keep important UI elements (like search fields or filters) visible while other content scrolls. This is useful for dialogs with long, scrollable content.

import { Button, Dialog, Flex, TextField, Text } from "@servicetitan/anvil2";
import { useState } from "react";

function ExampleComponent() {
  const [isOpen, setIsOpen] = useState(true);
  return (
    <Dialog open={isOpen} onClose={() => setIsOpen(false)}>
      <Dialog.Header>Filter Items</Dialog.Header>
      <Dialog.Content sticky>
        <TextField placeholder="Search items..." />
      </Dialog.Content>
      <Dialog.Content>
        <Flex direction="column" gap="2">
          {Array.from({ length: 50 }, (_, i) => (
            <Text key={i}>Item {i + 1}</Text>
          ))}
        </Flex>
      </Dialog.Content>
      <Dialog.Footer sticky>
        <Flex gap="3" justifyContent="flex-end">
          <Dialog.CancelButton>Cancel</Dialog.CancelButton>
          <Button appearance="primary">Apply</Button>
        </Flex>
      </Dialog.Footer>
    </Dialog>
  );
}

The search field will remain visible at the top while the list of items scrolls below it.

Choosing initial focus

By default, the Dialog focuses the first focusable element that is not the Dialog.CancelButton. To override this behavior, use the initialFocusResolver prop to specify which element receives focus when the dialog opens.The initialFocusResolver function receives an array of all focusable elements within the dialog and returns the one that should receive initial focus.

Closing dialogs

Clicking a Dialog.CancelButton or the close button inside of Dialog.Header will trigger the Dialog.onClose to run, where you can add a callback to control the open/close state of the dialog.

<Dialog open={isOpen} onClose={() => setIsOpen(false)}>
  {/* The header includes a close button that will trigger the Dialog.onClose */}
  <Dialog.Header>Header</Dialog.Header>
  <Dialog.Content>Content</Dialog.Content>
  <Dialog.Footer>
    {/* The cancel button will also trigger the Dialog.onClose */}
    <Dialog.CancelButton>Cancel</Dialog.CancelButton>
  </Dialog.Footer>
</Dialog>

Closing callbacks

In addition to onClose–which indicates a user has chosen to close a dialog–the component also offers two animation callbacks onCloseAnimationStart and onCloseAnimationComplete.You may use these callbacks to perform additional actions related to the presentation of the Dialog. For example, if you have a dialog containing a form, you may wish to reset the form state after the close animation has played so that the user doesn’t see an empty form briefly when closing the dialog.

const [open, setOpen] = useState(false);
const [field, setField] = useState("");

const handleSubmit = () => {
  setOpen(false);
};
const handleDialogAnimationComplete = () => {
  setField("");
};

return (
  <>
    <Button onClick={() => setOpen(true)}>Open</Button>
    <Dialog
      open={open}
      onClose={() => setOpen(false)}
      onCloseAnimationComplete={handleDialogAnimationComplete}
    >
      <Dialog.Header>What is your favorite color?</Dialog.Header>
      <Dialog.Content>
        <TextField
          label="Favorite color"
          value={field}
          onChange={(e) => setField(e.target.value)}
          style={{ width: "100%" }}
          autoComplete="off"
        />
      </Dialog.Content>
      <Dialog.Footer>
        <Button onClick={() => setOpen(false)}>Cancel</Button>
        <Button appearance="primary" onClick={handleSubmit}>
          Submit
        </Button>
      </Dialog.Footer>
    </Dialog>
  </>
);

Dialogs and Toasts

Due to the way the HTML dialog element renders in the browser’s top layer, the Dialog component includes an internal Toaster for rendering toast messages. This should be unnoticeable to implementors and users, but there may be edge cases the result in toasts not rendering as expected.Please reach out to us in the #ask-designsystem channel on Slack if any edge cases related to dialogs and toasts are found!

Anti-Patterns

Conditional rendering

The openness should be controlled by the open prop and not by conditional rendering — this is an anti-pattern for Dialog.

❌
{condition && <Dialog open>...</Dialog>}

✅
<Dialog open={condition}>...</Dialog>

Resetting content

HTML Dialog show/hide content but it doesn’t remove from the DOM which means the reset doesn’t happen automatically. To do the reset, use key on <Dialog.Content> . Since <Dialog.Content> is always present in DOM, you can add conditional to, or in, the <Dialog.Content> as well.

More details

Dialog uses HTML Dialog which is powered by HTML top-layers. This puts them on top of EVERYTHING regardless z-index and we use the HTML top-layer to avoid stacking context and z-index issues, ensuring Dialog always appear above all content without needing manual z-index adjustments. Dialog internally has custom mechanism to ensure Toasts to be on top for ServiceTitan app and requires Dialog to be present on page load.

<Dialog
  open={true}
  onClose={() => setIsOpen(false)}
  disableCloseOnClickOutside={false}
  disableCloseOnEscape={false}
  fullScreen={false}
  size="medium"
  onCloseAnimationComplete={() => {}}
  onCloseAnimationStart={() => {}}
  onOpenAnimationComplete={() => {}}
  onOpenAnimationStart={() => {}}
>
  <Dialog.Header>Header</Dialog.Header>
  <Dialog.Content>Content</Dialog.Content>
  <Dialog.Footer>
    <Dialog.CancelButton>Cancel</Dialog.CancelButton>
  </Dialog.Footer>
</Dialog>

`Dialog` Props

In addition to the props listed below, the Dialog component can accept any valid HTML dialog props.

number

default:"0"

Screen the first next() opens from a closed DrillDown stack. The dialog starts with no active screen. Closing the dialog restores this index.

boolean

default:"false"

When true, clicking outside the dialog will not close it.

boolean

default:"false"

When true, pressing the escape key will not close the dialog.

boolean

Enables scroll chaining behavior.

boolean

default:"false"

(focusables: FocusableElement[]) => FocusableElement

Given an array of focusable elements, returns the element that should receive initial focus.

(e: MouseEvent) => void

Callback when clicking outside the dialog.

() => void

Indicates the user has closed the dialog. Use this to update your state.

() => void

Callback indicating the dialog has animated out. Use this to clean up views as needed.

() => void

Callback indicating the dialog is beginning to animate out.

() => void

Callback indicating the dialog has animated in.

() => void

Callback indicating the dialog is beginning to animate in.

boolean

default:"false"

"medium" | "large" | "xlarge"

default:"medium"

<Dialog.Header>Dialog Header</Dialog.Header>

The Dialog.Header component can accept any valid HTML header props.

<Dialog.Content sticky>Dialog content</Dialog.Content>

`Dialog.Content` Props

In addition to the props listed below, the Dialog.Content component can accept any valid HTML div props.

boolean

default:"false"

When true, the content will stick below the header during scroll.

<Dialog.Footer sticky={false}>
  <Button>Action</Button>
</Dialog.Footer>

boolean

default:"false"

<Dialog.CancelButton appearance="secondary" onClick={() => {}}>
  Cancel
</Dialog.CancelButton>

`Dialog.CancelButton` Props

The Dialog.CancelButton component can accept the same props as the Button component.

​Anatomy

​Options

​Body content

​Footer actions

​Sizing

​Default

​Large

​Extra Large

​Fullscreen

​Sizing table

​Behavior

​Overflow handling

​Scrolling

​Usage Guidelines

​Alternatives

​Dialog vs Alert

​Dialog vs Drawer

​Dialog vs Popover

​How to Use

​Multi-step Dialogs

​Forms in Dialogs

​Avoid stacking smaller Dialogs together

​Stacking a Dialog with a fullscreen Dialog

​Content

​Write titles as verbs

​Make body content concise and actionable

​Buttons should be clear, predictable, and action-oriented

​Keyboard Interaction

​Accessibility

​Focus management

Trap focus within the Dialog

First focus management

Return focus on close

​Code

​Common Examples

​Opening dialogs

​Rendering content on open

​Sticky Content

​Choosing initial focus

​Closing dialogs

​Closing callbacks

​Dialogs and Toasts

​Anti-Patterns

​Conditional rendering

​Resetting content

​More details

​Dialog Props

​Dialog.Header Props

​Dialog.Content Props

​Dialog.Footer Props

​Dialog.CancelButton Props

Anatomy

Options

Body content

Footer actions

Sizing

Default

Large

Extra Large

Fullscreen

Sizing table

Behavior

Overflow handling

Scrolling

Usage Guidelines

Alternatives

Dialog vs Alert

Dialog vs Drawer

Dialog vs Popover

How to Use

Multi-step Dialogs

Forms in Dialogs

Avoid stacking smaller Dialogs together

Stacking a Dialog with a fullscreen Dialog

Content

Write titles as verbs

Make body content concise and actionable

Buttons should be clear, predictable, and action-oriented

Keyboard Interaction

Accessibility

Focus management

Code

Common Examples

Opening dialogs

Rendering content on open

Sticky Content

Choosing initial focus

Closing dialogs

Closing callbacks

Dialogs and Toasts

Anti-Patterns

Conditional rendering

Resetting content

More details

`Dialog` Props

`Dialog.Header` Props

`Dialog.Content` Props

`Dialog.Footer` Props

`Dialog.CancelButton` Props