Drawer - Web

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

Anatomy

The Drawer consists of six primary elements that work together to slide content onto the page from the right.

Header
Header actions (Optional)
Close action
Body content
Backdrop
Footer actions

Options

The Drawer supports flexible content, header actions, footer actions, and sizing configurations to accommodate various flyout scenarios.

Header actions

Drawer supports an optional overflow menu in the header for secondary operations related to the drawer content. Header actions appear to the left of the close action.

Body content

Drawer supports any type of content in the body. Drawer supports several types of action groupings. These typically include one primary action and may include elements such as links or destructive actions.

Sizing

Drawer supports 4 sizing options: small, medium (default), large, and extra large.

Sizing	Width	Height
Small	22.5rem / 360px	100%
Medium (default)	35rem / 560px	100%
Large	48rem / 768px	100%
Extra Large	70rem / 1120px	100%

Behavior

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

Overflow handling

Header and footer content in Drawer wraps rather than truncates. Footer actions support custom overflow behavior when needed.

Scrolling

The body region of Drawer scrolls when space is not available. The footer can be configured to scroll with the body but is typically sticky.

Usage Guidelines

Use Drawer to show information or a task without navigating to another page.

Standard	Requirement
DoPosition on the right	Drawers always appear on the right side of the page; see Position the Drawer on the right.
DoAlways use a backdrop	The backdrop reinforces the focused nature of Drawer and prevents de-synced states; see Always use a backdrop.
DoExtend to full height	Drawers always extend to 100% the height of the browser window; see Always extend the Drawer to the screen’s full height.
Don’tUse for exclusive, essential flows	Drawers should not be used for steps essential to a flow. The exception is if the Drawer is acting as a supplemental, redundant place for those steps.
Don’tUse to communicate page errors	Using a Drawer to convey errors is an anti-pattern. It requires a user to actively remember its contents once the Drawer is closed. See the error pattern for alternatives.
Don’tUse to confirm actions	Use the Dialog for confirmations instead.
Don’tPosition on the left	Don’t position a Drawer on the left side of the page; see Position the Drawer on the right.
Don’tExcluding the backdrop	Don’t exclude the backdrop; if side content must not have a backdrop, integrate the content directly on the page instead; see Always use a backdrop.
Don’tOffsetting Drawer height	Don’t offset the Drawer to fit below other elements on the page; see Always extend the Drawer to the screen’s full height.

Alternatives

Consider integrating the content directly on the page instead of using a Drawer. This allows users to continue to both see and interact with the rest of the content on the page.

Drawer vs Dialog

	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

How to Use

Position the Drawer on the right

Drawers always appear on the right side of the page.

Don’t

Always use a backdrop

The backdrop reinforces the focused nature of Drawer and prevents de-synced states. If side content must not have a backdrop, integrate the content directly on the page instead.

Don’t

Always extend the Drawer to the screen’s full height

Drawers will always extend to 100% the height of the browser window. Don’t offset the Drawer to fit below other elements on the page.

Don’t

Dialogs on top of Drawers

Avoid stacking overlay elements. A confirmation message through a Dialog is an exception. If a confirmation Dialog is needed within a Drawer, use an alternative to Drawer.

Content

Content within the Drawer should be clear, organized, and support the task or information being displayed.

Keyboard Interaction

Users can navigate the Drawer using standard keyboard controls.

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

Accessibility

Focus management

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

Trap focus within the Drawer

By default, the Drawer will trap focus within itself. Elements outside of the Drawer would not be accessible by keyboard.

First focus management

What elements Drawer focuses on open depends on a few factors:

If the body content has a focusable element, Drawer focuses on the first of these elements.
If the body does not have a focusable element, 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 Drawer is closed and the original context that triggered the Drawer is still present, focus should return to the element that triggered the Drawer. For more guidance on focus management with dynamic content, see changing content best practices.

Code

Implementation
Drawer Props
Drawer.Header Props
Drawer.Content Props
Drawer.Footer Props

Common Examples

import { Button, Drawer } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Drawer open>
      <Drawer.Header>Header text</Drawer.Header>
      <Drawer.Content>Body text</Drawer.Content>
      <Drawer.Footer>
        <Button appearance="primary">Footer Button</Button>
      </Drawer.Footer>
    </Drawer>
  );
}

Closing Drawers

Clicking a Drawer.CancelButton or the close button in the Drawer.Header will trigger the onClose handler. A callback can be added to a Drawer.CancelButton or any Button in the Drawer.Footer to further control the open state of the Drawer.

Closing callbacks

In addition to onClose–which indicates a user has chosen to close a drawer–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 Drawer. For example, if you have a drawer 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 drawer.

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

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

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

Sticky Content

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

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

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

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

Drawers and Toasts

Due to the way the HTML dialog element renders in the browser’s top layer, the Drawer 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 drawers 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 Drawer.

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

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

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 <Drawer.Content> . Since <Drawer.Content> is always present in DOM, you can add conditional to, or in, the <Drawer.Content> as well.

More details

Drawer 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 Drawer always appear above all content without needing manual z-index adjustments. Drawer internally has custom mechanism to ensure Toasts to be on top for ServiceTitan app and requires Drawer to be present on page load.

<Drawer
  open={true}
  onClose={() => setIsOpen(false)}
  disableCloseOnClickOutside={false}
  disableCloseOnEscape={false}
  size="medium"
  onCloseAnimationComplete={() => {}}
  onCloseAnimationStart={() => {}}
  onOpenAnimationComplete={() => {}}
  onOpenAnimationStart={() => {}}
>
  <Drawer.Header>Header</Drawer.Header>
  <Drawer.Content>Content</Drawer.Content>
  <Drawer.Footer>
    <Button>Action</Button>
  </Drawer.Footer>
</Drawer>

`Drawer` Props

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

number

default:"0"

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

boolean

default:"false"

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

boolean

default:"false"

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

boolean

Enables scroll chaining behavior.

(focusables: (HTMLElement | SVGElement)[]) => (HTMLElement | SVGElement)

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

(e: MouseEvent) => void

Callback when clicking outside the drawer.

() => void

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

() => void

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

() => void

Callback indicating the drawer is beginning to animate out.

() => void

Callback indicating the drawer has animated in.

() => void

Callback indicating the drawer is beginning to animate in.

boolean

default:"false"

"small" | "medium" | "large" | "xlarge"

default:"medium"

<Drawer.Header
  actions={[
    { label: "Edit", onClick: () => {} },
    { label: "Duplicate", onClick: () => {} },
    { label: "Delete", onClick: () => {} },
  ]}
>
  Drawer Header
</Drawer.Header>

In addition to the props listed below, the Drawer.Header component can accept any valid HTML header props.

{ label: string; onClick: () => void; disabled?: boolean; icon?: Svg }[]

Overflow menu items rendered to the left of the close button. Each item maps to a Menu.Item.

<Drawer.Content sticky>Drawer content</Drawer.Content>

`Drawer.Content` Props

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

boolean

default:"false"

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

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

In addition to the props listed below, the Drawer.Footer component can accept any valid HTML footer props.

boolean

default:"false"

​Anatomy

​Options

​Header actions

​Body content

​Footer actions

​Sizing

​Behavior

​Overflow handling

​Scrolling

​Usage Guidelines

​Alternatives

​Drawer vs Dialog

​How to Use

​Position the Drawer on the right

​Always use a backdrop

​Always extend the Drawer to the screen’s full height

​Dialogs on top of Drawers

​Content

​Keyboard Interaction

​Accessibility

​Focus management

Trap focus within the Drawer

First focus management

Return focus on close

​Code

​Common Examples

​Closing Drawers

​Closing callbacks

​Sticky Content

​Drawers and Toasts

​Anti-Patterns

​Conditional rendering

​Resetting content

​More details

​Drawer Props

​Drawer.Header Props

​Drawer.Content Props

​Drawer.Footer Props

Anatomy

Options

Header actions

Body content

Footer actions

Sizing

Behavior

Overflow handling

Scrolling

Usage Guidelines

Alternatives

Drawer vs Dialog

How to Use

Position the Drawer on the right

Always use a backdrop

Always extend the Drawer to the screen’s full height

Dialogs on top of Drawers

Content

Keyboard Interaction

Accessibility

Focus management

Code

Common Examples

Closing Drawers

Closing callbacks

Sticky Content

Drawers and Toasts

Anti-Patterns

Conditional rendering

Resetting content

More details

`Drawer` Props

`Drawer.Header` Props

`Drawer.Content` Props

`Drawer.Footer` Props