Tab - Web

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

Anatomy

The Tab consists of five primary elements that work together to organize related content into groups.

Tablist
Tab content or panel
Tab
Active Tab
Divider

Options

The Tab supports active state, label, and width configurations to accommodate various content organization scenarios.

Active

Tabs always have exactly one active Tab at a time. Typically, the first Tab in a group is the default active Tab.

Label

Custom labels

The Tab label can be replaced as needed with custom, non-interactive content.

Width options

Fixed width

By default, an individual Tab will be as wide as its text, with a minimum width of 48px. This is useful when Tabs are in wide containers.

Filled width

Tabs can also fill all available width in its container. This is useful in smaller containers.

Behavior

The Tab responds to space constraints with compression and overflow behaviors while maintaining consistent visual states.

Visual States

Visual states apply independently of the active state.

Disabled

Disabled Tabs are not supported. Consider either removing the Tab, or disabling the Tab’s content in some way instead.

Tab compression

With both fixed and filled Tab widths, when not enough space is available, the Tabs will shrink, but not truncate, to fit the container. A minimum of 1rem of space will exist between Tab labels.

Behavior of filled Tabs with minimal space
available

Tab group overflow

When compression is not enough, the Tab group will scroll overflow, rather than truncate. A user can both scroll to reveal (either by keyboard or mouse), or use the next / previous buttons provided by the group.

Usage Guidelines

Use the Tab to organize content into multiple sections. Tabs help to break up content into easier to process information.

Standard	Requirement
DoKeep exactly one Tab active	Exactly one Tab should always be active in a Tab list; see Always have one Tab active.
DoKeep Tab scope clear	Keep the scope of content change to inside the boundaries of Tabs; see Make the scope of Tabs clear.
DoPair Tabs with informational Chips	Pair a Tab with a Chip when the number value is informational in nature; see Showing numerical values.
DoPlace status Alert near Tabs	Pair a status with an Alert, placed below the Tab for Tab-scoped status or above the Tabs for cross-Tab status; place it below the Tabs as a rule; see Representing status.
Don’tPrimary navigation	Tabs should not represent the primary method of navigation. A side or top nav is used instead.
Don’tStarting an action	Tabs should not be used to directly start an action, such as a flow.
Don’tUnclear content organization	Tabs should not be used when content cannot be organized in a way a user would understand.
Don’tDirectly comparing tab content	Tabs should not be used when information between tabs is being directly compared.
Don’tFiltering page content	Tabs should not be used for filtering content on the page.
Don’tNo active tab	Don’t have a tab list where no tab is active; see Always have one Tab active.
Don’tMultiple selected tabs	Don’t show multiple tabs as selected; see Always have one Tab active.
Don’tChanging content outside Tab scope	Don’t change content outside of the Tab scope between Tabs; see Make the scope of Tabs clear.
Don’tColoring Chips in Tabs	Don’t add color to Chips when used in Tabs; see Showing numerical values.
Don’tStatus directly in Tab labels	Don’t represent status directly in the Tabs — this isn’t a common experience and raises accessibility concerns for keyboard and screen reader users; see Representing status.

Alternatives

Tab vs Details

Details are used to show additional information around a sub-topic on a page, while a Tab categorizes information. The context of Details is small, non-essential information, while Tabs can categorize both small and large, essential and non-essential information.

Tab vs Segmented Control

Segmented Control allows users to change the presentation format of displayed content or to filter it. Tabs changes the view to show new content.

Tab vs Side Nav

Side Navs and Tabs perform similar tasks of organizing content. In most situations, Side Navs are a higher level of the navigation structure compared to Tabs. Side Navs are also able to organize less related items together compared to Tabs.

Tab vs Stepper

Tabs help organize information about a subject on the page, while a Stepper helps complete a flow. They can’t substitute for each other, although both could be used on the same page.

How to Use

Always have one Tab active

Exactly one Tab should always be active in a Tab list.

Don’t

Don’t have a tab list where no tab is active.

Don’t

Don’t show multiple tabs as selected

Make the scope of Tabs clear

A user should be able to understand what is and isn’t part of a Tab list. This usually means content below the Tabs, extending across the Tab’s divider line. Additional visual consideration may be needed if the Tab scope is a sub section of a page.

Keep the scope of content change to inside the boundaries of Tabs.

Don’t

Don’t change content outside of the Tab scope between Tabs.

Showing numerical values

Tabs can utilize small Chips to convey value. Pair a Tab with a Chip when the number value is informational in nature.

If a numerical value is relevant, it may be optionally added to a Tab.

Don’t

Don’t add color to Chips when used in Tabs.

Representing status

When a status, typically an error, needs representation at the Tab level, pair it with an Alert, either below the Tab or above the Tab depending on how critical it is a user should know about the status. As a rule, place it below the Tabs. Don’t represent status directly in the Tabs. Status in Tabs directly is not a common experience in apps, in addition to accessibility concerns for keyboard and screenreader users.

Don’t

Nested Tabs

Use caution when nesting Tabs within Tabs, as they can be difficult to use simultaneously. Consider alternative ways of organizing information, such as a Side Nav, Details, or Stepper.

Content

Content within the Tab should clearly communicate each section through descriptive labels.

Keyboard Interaction

Users can navigate the Tab using standard keyboard controls.

Key	Description
Tab	Moves focus to the next focusable element outside of the Tab Group.
Right Arrow	Moves focus to the next Tab. If on the last Tab in the group, it focuses on the first Tabbed element.
Left Arrow	Moves focus to the previous Tab. If on the first Tab in the group, it focuses on the right Tabbed element.
Space or Enter	Selects the focused Tab.

Manual activation only

Tab groups only support manual tab activation, meaning keyboard users can cycle through tab focus, but must also activate the tab with a separate key.

Accessibility

Anvil provides all the accessibility pieces needed. There are some additional accessibility considerations if new behavior is added on top of the design system.

Automatic tab activation

This refers to tabs being automatically activates on focus. This is considered an acceptable behavior, but is not provided by Anvil. If a design needs this feature, consider following the W3C ARIA implementation of automatic activation, including how it handles keyboard interaction. Automatic tabs do not need a new visual treatment.

Use caution when adding actions in Tabs

Be sure that when adding an action of any kind to Tabs that it is still reachable by keyboard. This is especially true if your Tab action also uses arrow keys. For more guidance on custom tab behaviors and keyboard interaction, see changing content best practices.

Code

Implementation
Tab Props
Tab.List Props
Tab.Button Props
Tab.Panel Props

Common Examples

import { Tab } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Tab>
      <Tab.List>
        <Tab.Button id="t-1" controls="p-1">
          Tab 1
        </Tab.Button>
        <Tab.Button id="t-2" controls="p-2">
          Tab 2
        </Tab.Button>
      </Tab.List>
      <Tab.Panel id="p-1">Tab 1 content...</Tab.Panel>
      <Tab.Panel id="p-2">Tab 2 content...</Tab.Panel>
    </Tab>
  );
}

Basic Tabs

Tabs are used to separate large blocks of content relevant to the user’s current context. Four components are used to makeup Anvil tabs: Tab, Tab.List, Tab.Button, and Tab.Panel.

Notes

There should always be an equal number of Tab.Button and Tab.Panel components.
Values in the controls prop of each Tab.Button component should match the id of the corresponding Tab.Panel.

Changing the Default Tab

By default, the content of the Tab.Panel associated to the first Tab.Button will be displayed. To change this behavior, supply the index of the Tab.Button that should be displayed first to the defaultIndex of the parent Tab.

Controlled Tabs

To control the active tab from outside the component, use the index and onIndexChange props. This is useful when you need to synchronize the active tab with external state, such as a URL parameter or another UI element.

When using index, you must also provide onIndexChange to keep the active tab in sync when the user interacts with it directly. Without onIndexChange, the tab will appear frozen.

React Accessibility

An Anvil Tab.Button cannot be disabled.
When a Tab.Button has focus, the left and right arrow keys and enter can be used to navigate tabs.

For more guidance on custom tab behaviors and keyboard interaction, see changing content best practices.

<Tab defaultIndex={0}>
  <Tab.List>
    <Tab.Button id="t-1" controls="p-1">
      Tab 1
    </Tab.Button>
  </Tab.List>
  <Tab.Panel id="p-1">Content</Tab.Panel>
</Tab>

`Tab` Props

number

default:"0"

The index of the tab that should be active by default. Use for uncontrolled usage. For controlled usage, use index instead.

boolean

default:"false"

Whether the tabs should fill the available width.

number

The index of the currently active tab. Use for controlled usage. For uncontrolled usage, use defaultIndex instead.

(index: number) => void

Callback fired when the active tab changes. Use with index for controlled usage.

<Tab.List>
  <Tab.Button id="t-1" controls="p-1">
    Tab 1
  </Tab.Button>
</Tab.List>

`Tab.List` Props

The Tab.List component accepts any valid HTML div props, and does not have any custom props.

<Tab.Button
  id="t-1"
  controls="p-1"
  onClick={(e, index) => console.log("Clicked", index)}
>
  Tab 1
</Tab.Button>

`Tab.Button` Props

The Tab.Button component accepts any valid HTML button props, other than disabled, as well as the following:

string

required

id of the Tab.Panel that this button controls.

string

required

Unique identifier for the tab button.

(e: MouseEvent, index?: number) => void

<Tab.Panel id="p-1">Tab content</Tab.Panel>

`Tab.Panel` Props

The Tab.Panel component accepts any valid HTML div props in addition to what is listed below.

string

required

Unique identifier for the tab panel. Used by the controls prop of the Tab.Button component to determine when to show this panel.

​Anatomy

​Options

​Active

​Label

​Custom labels

​Width options

​Fixed width

​Filled width

​Behavior

​Visual States

​Disabled

​Tab compression

​Tab group overflow

​Usage Guidelines

​Alternatives

​Tab vs Details

​Tab vs Segmented Control

​Tab vs Side Nav

​Tab vs Stepper

​How to Use

​Always have one Tab active

​Make the scope of Tabs clear

​Showing numerical values

​Representing status

​Nested Tabs

​Content

​Keyboard Interaction

​Manual activation only

​Accessibility

​Automatic tab activation

​Use caution when adding actions in Tabs

​Code

​Common Examples

​Basic Tabs

​Notes

​Changing the Default Tab

​Controlled Tabs

​React Accessibility

​Tab Props

​Tab.List Props

​Tab.Button Props

​Tab.Panel Props

Anatomy

Options

Active

Label

Custom labels

Width options

Fixed width

Filled width

Behavior

Visual States

Disabled

Tab compression

Tab group overflow

Usage Guidelines

Alternatives

Tab vs Details

Tab vs Segmented Control

Tab vs Side Nav

Tab vs Stepper

How to Use

Always have one Tab active

Make the scope of Tabs clear

Showing numerical values

Representing status

Nested Tabs

Content

Keyboard Interaction

Manual activation only

Accessibility

Automatic tab activation

Use caution when adding actions in Tabs

Code

Common Examples

Basic Tabs

Notes

Changing the Default Tab

Controlled Tabs

React Accessibility

`Tab` Props

`Tab.List` Props

`Tab.Button` Props

`Tab.Panel` Props