Drilldown – Code

Common Examples

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

function ExampleComponent() {
  return (
    <Dialog>
      <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>
      <DrillDown index={0}>
        <DrillDown.Header>DrillDown Index 0</DrillDown.Header>
        <DrillDown.Content>This is the drilldown body content.</DrillDown.Content>
        <DrillDown.Footer>
          <Flex gap="3" justifyContent="flex-end">
            <DrillDown.PrevButton>Cancel</DrillDown.PrevButton>
            <DrillDown.NextButton appearance="primary">
              Continue
            </DrillDown.NextButton>
          </Flex>
        </DrillDown.Footer>
      </DrillDown>
    </Dialog>
  );
}

Use as children of `Dialog`, `Drawer`, or `Page.Panel`

Any number of DrillDown components can be added as children of the Dialog, Drawer, or Page.Panel component. When a DrillDown is visible, it will cover the entire contents of the Dialog or Drawer.

<Dialog>
  <Dialog.Header>{...}</Dialog.Header>
  <Dialog.Content>{...}</Dialog.Content>
  <Dialog.Footer>{...}</Dialog.Footer>

  <DrillDown index={0}>{...}</DrillDown>
  <DrillDown index={1}>{...}</DrillDown>
  <DrillDown index={2}>{...}</DrillDown>
  <DrillDown index={3}>{...}</DrillDown>
</Dialog>

<Drawer>
  <Drawer.Header>{...}</Drawer.Header>
  <Drawer.Content>{...}</Drawer.Content>
  <Drawer.Footer>{...}</Drawer.Footer>

  <DrillDown index={0}>{...}</DrillDown>
  <DrillDown index={1}>{...}</DrillDown>
  <DrillDown index={2}>{...}</DrillDown>
  <DrillDown index={3}>{...}</DrillDown>
</Drawer>

Each DrillDown requires a unique indexDrillDown sibling components are identified by their index prop. Numbers used for the index prop are zero-based, and calling next or clicking the DrillDown.NextButton will display the next index in numerical order.

Uncontrolled usage

Set defaultDrillDownIndex on the host (Dialog, Drawer, or Page.Panel) to choose which DrillDown screen the first next() opens from a closed stack. The prop type is number and defaults to 0. The host starts with no active screen. Closing the host restores this index.Use defaultDrillDownIndex when that first next() should not open index 0—for example, skipping an intro screen.

import { useState } from "react";
import { Drawer, DrillDown, Flex } from "@servicetitan/anvil2";

function ExampleComponent() {
  const [isOpen, setIsOpen] = useState(true);

  return (
    <Drawer
      open={isOpen}
      onClose={() => setIsOpen(false)}
      defaultDrillDownIndex={1}
    >
      <Drawer.Header>Drawer Header</Drawer.Header>
      <Drawer.Content>This is the drawer body content.</Drawer.Content>
      <Drawer.Footer>
        <Flex gap="3" justifyContent="flex-end">
          <Drawer.CancelButton>Cancel</Drawer.CancelButton>
          <DrillDown.NextButton appearance="primary">Continue</DrillDown.NextButton>
        </Flex>
      </Drawer.Footer>

      <DrillDown index={0} onClose={() => setIsOpen(false)}>
        <DrillDown.Header>Intro</DrillDown.Header>
        <DrillDown.Content>Optional intro screen.</DrillDown.Content>
        <DrillDown.Footer>
          <Flex gap="3" justifyContent="flex-end">
            <DrillDown.PrevButton>Cancel</DrillDown.PrevButton>
            <DrillDown.NextButton appearance="primary">
              Continue
            </DrillDown.NextButton>
          </Flex>
        </DrillDown.Footer>
      </DrillDown>

      <DrillDown index={1} onClose={() => setIsOpen(false)}>
        <DrillDown.Header>Main step</DrillDown.Header>
        <DrillDown.Content>
          Screen the first `next()` opens (`defaultDrillDownIndex={1}`).
        </DrillDown.Content>
        <DrillDown.Footer>
          <Flex gap="3" justifyContent="flex-end">
            <DrillDown.PrevButton>Back</DrillDown.PrevButton>
            <DrillDown.NextButton appearance="primary">
              Continue
            </DrillDown.NextButton>
          </Flex>
        </DrillDown.Footer>
      </DrillDown>
    </Drawer>
  );
}

With defaultDrillDownIndex={1}, the first next opens index 1. Index 0 stays in the tree for later setIndex(0) jumps but is not reached by Next/Prev alone—back from the start index closes the flow.

Using `DrillDown.NextButton` and `DrillDown.PrevButton`

The DrillDown can be used with uncontrolled state by using the DrillDown.NextButton to move forward to each DrillDown index in ascending numerical order. The first next call opens defaultDrillDownIndex on the host. The DrillDown.PrevButton will similarly move backward in descending numerical order, and will close the DrillDown if there is no previous screen.

Controlled usage

Controlled navigation still uses defaultDrillDownIndex on the host for the first next() from a closed stack and for restore-on-close. Spread useDrillDown().drillDownProps onto the same host, then call next, back, or setIndex for programmatic moves. Omit the prop to restore to 0 (shown below), or pass a non-zero value when the first next() should open a later screen.

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

function ExampleComponent() {
  const { drillDownProps, back, next } = useDrillDown();
  const [isOpen, setIsOpen] = useState(true);

  return (
    <Drawer {...drillDownProps} open={isOpen} onClose={() => setIsOpen(false)}>
      <Drawer.Header>Drawer Header</Drawer.Header>
      <Drawer.Content>This is the drawer body content.</Drawer.Content>
      <Drawer.Footer>
        <Flex gap="3" justifyContent="flex-end">
          <Drawer.CancelButton>Cancel</Drawer.CancelButton>
          <Button appearance="primary" onClick={next}>Continue</Button>
        </Flex>
      </Drawer.Footer>

      <DrillDown index={0} onClose={() => setIsOpen(false)}>
        <DrillDown.Header>DrillDown Index 0</DrillDown.Header>
        <DrillDown.Content>This is the drilldown body content.</DrillDown.Content>
        <DrillDown.Footer>
          <Flex gap="3" justifyContent="flex-end">
            <Button onClick={back}>Cancel</Button>
            <Button appearance="primary" onClick={next}>
              Continue
            </Button>
          </Flex>
        </DrillDown.Footer>
      </DrillDown>
    </Drawer>
  );
}

Using the `useDrillDown` hook

The useDrillDown hook returns a next and back function to allow for programmatically navigating between DrillDown components in numerical index order. (The hook also returns a setIndex function to allow navigating to arbitrary index values.)To allow this hook to work, the drillDownProps return value also needs to be spread onto the parent component.

import { useState } from "react";
import { Drawer, useDrillDown } from "@servicetitan/anvil2";

function ExampleComponent() {
  const { drillDownProps, back, next } = useDrillDown();
  const [isOpen, setIsOpen] = useState(true);

  return (
    <Drawer {...drillDownProps} open={isOpen} onClose={() => setIsOpen(false)}>
      {...}
    </Drawer>
  );
}

Closing from within a `DrillDown`

By default, the DrillDown.Header does not display a close button. To display a close button in the DrillDown.Header, add an onClose handler to the DrillDown.

<DrillDown index={0} onClose={() => setOpen(false)}>
  <DrillDown.Header>DrillDown Index 0</DrillDown.Header>
  <DrillDown.Content>This is the drilldown body content.</DrillDown.Content>
  <DrillDown.Footer>
    <Flex gap="3" justifyContent="flex-end">
      <DrillDown.PrevButton>Cancel</DrillDown.PrevButton>
      <DrillDown.NextButton appearance="primary">
        Continue
      </DrillDown.NextButton>
    </Flex>
  </DrillDown.Footer>
</DrillDown>

Header actions

To add an overflow menu to the DrillDown.Header, pass an actions array. The menu appears to the left of the close button, or on its own when the DrillDown has no onClose.Actions belong to the screen that defines them. A DrillDown does not inherit the actions from Drawer.Header, so pass the commands that apply to each screen.

<DrillDown index={0} onClose={() => setOpen(false)}>
  <DrillDown.Header
    actions={[
      { label: "Edit", onClick: () => {} },
      { label: "Duplicate", onClick: () => {} },
      { label: "Delete", onClick: () => {} },
    ]}
  >
    DrillDown Index 0
  </DrillDown.Header>
  <DrillDown.Content>This is the drilldown body content.</DrillDown.Content>
</DrillDown>

<DrillDown index={0} onClose={() => setOpen(false)}>
  <DrillDown.Header>DrillDown Index 0</DrillDown.Header>
  <DrillDown.Content>This is the drilldown body content.</DrillDown.Content>
  <DrillDown.Footer>
    <Flex gap="3" justifyContent="flex-end">
      <DrillDown.PrevButton>Cancel</DrillDown.PrevButton>
      <DrillDown.NextButton appearance="primary">
        Continue
      </DrillDown.NextButton>
    </Flex>
  </DrillDown.Footer>
</DrillDown>

`DrillDown` Props

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

number

required

The index of the DrillDown screen in the navigation sequence. This index is zero-based.

() => void

Called when the close button in the header is clicked. The close button is only displayed in the DrillDown.Header if there is an onClose provided.

Host overlay props

defaultDrillDownIndex is not a prop on DrillDown. Set it on the host overlay that owns the drill flow:

number

default:"0"

Screen the first next() opens from a closed stack. The host starts with no active screen. Closing the host restores this index. Available on Dialog, Drawer, and Page.Panel.

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

`DrillDown.Header` Props

In addition to the props listed below, the DrillDown.Header component can accept any valid HTMLheader 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. The menu appears when the array is non-empty.

"h1" | "h2" | "h3" | "h4" | "h5" | "h6"

default:"h1"

Customizes the heading level of the DrillDown.Header

<DrillDown.Content>DrillDown content</DrillDown.Content>

`DrillDown.Content` Props

The DrillDown.Content component can accept any valid HTML div props.

<DrillDown.Footer>
  <Flex gap="3" justifyContent="flex-end">
    <Button onClick={back}>Back</Button>
    <Button appearance="primary" onClick={next}>
      Continue
    </Button>
  </Flex>
</DrillDown.Footer>

The DrillDown.Footer component can accept any valid HTML footer props.

<DrillDown.NextButton appearance="primary">
  Continue
</DrillDown.NextButton>

`DrillDown.NextButton` Props

The DrillDown.NextButton component can accept the same props as the Button component. This button takes the user to the next DrillDown index (e.g. if the index 1 DrillDown is visible, it will move to index 2).

<DrillDown.PrevButton>
  Back
</DrillDown.PrevButton>

`DrillDown.PrevButton` Props

The DrillDown.PrevButton component can accept the same props as the Button component. This button takes the user to the previous DrillDown. If there is no previous DrillDown, it will close the DrillDown.

const { drillDownProps, setIndex, back, next } = useDrillDown();

`useDrillDown` hook

The useDrillDown hook returns four values:

object

This object is required to be spread on the parent component (Drawer, Dialog) for the DrillDown to work in a controlled manner using the useDrillDown hook.

() => void

Calling this function takes the user to the next DrillDown index (e.g. if the index 1 DrillDown is visible, it will move to index 2).

() => void

Calling this function takes the user to the previous DrillDown. If there is no previous DrillDown, it will close the DrillDown.

(index: number | undefined) => void

Calling this function takes the user to the DrillDown index that is passed into the function. If setIndex is called with undefined, it will close the DrillDown.

Anvil2 Web

Resources

Drilldown – Code

Common Examples

Use as children of `Dialog`, `Drawer`, or `Page.Panel`

Uncontrolled usage

Using `DrillDown.NextButton` and `DrillDown.PrevButton`

Controlled usage

Using the `useDrillDown` hook

Closing from within a `DrillDown`

Header actions

`DrillDown` Props

Host overlay props

`DrillDown.Header` Props

`DrillDown.Content` Props

`DrillDown.Footer` Props

`DrillDown.NextButton` Props

`DrillDown.PrevButton` Props

`useDrillDown` hook

​Common Examples

​Use as children of Dialog, Drawer, or Page.Panel

​Uncontrolled usage

​Using DrillDown.NextButton and DrillDown.PrevButton

​Controlled usage

​Using the useDrillDown hook

​Closing from within a DrillDown

​Header actions

​DrillDown Props

​Host overlay props

​DrillDown.Header Props

​DrillDown.Content Props

​DrillDown.Footer Props

​DrillDown.NextButton Props

​DrillDown.PrevButton Props

​useDrillDown hook

Common Examples

Use as children of `Dialog`, `Drawer`, or `Page.Panel`

Uncontrolled usage

Using `DrillDown.NextButton` and `DrillDown.PrevButton`

Controlled usage

Using the `useDrillDown` hook

Closing from within a `DrillDown`

Header actions

`DrillDown` Props

Host overlay props

`DrillDown.Header` Props

`DrillDown.Content` Props

`DrillDown.Footer` Props

`DrillDown.NextButton` Props

`DrillDown.PrevButton` Props

`useDrillDown` hook