## Anatomy
The Tab consists of five primary elements that work together to organize related content into groups.
1. Tablist
2. Tab content or panel
3. Tab
4. Active Tab
5. 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.
### 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.
### When not to use
Tabs should not be used:
* To represent the primary method of navigation. A side or top nav is used instead.
* To directly start an action, such as a flow.
* When content cannot be organized in a way a user would understand.
* When information between tabs is being directly compared.
* For filtering content on the page.
### 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.
```tsx lines theme={null}
import { Tab } from "@servicetitan/anvil2";
function App() {
return (
Tab A
Tab B
Tab C
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Tab } from "@servicetitan/anvil2";
function App() {
return (
Tab A
Tab B
Tab C
);
}
export default App;
```
**Don't**
Don't have a tab list where no tab is active.
```tsx lines theme={null}
import { Tab } from "@servicetitan/anvil2";
function App() {
return (
Tab A
Tab B
Tab C
);
}
export default App;
```
**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.
```tsx lines theme={null}
import { Tab, Text, Button } from "@servicetitan/anvil2";
function App() {
return (
Page title
Tab A
Tab B
Tab C
Scope of Tab AScope of Tab BScope of Tab C
);
}
export default App;
```
**Do**
Keep the scope of content change to inside the boundaries of Tabs.
```tsx lines theme={null}
import { Tab, Text, Button } from "@servicetitan/anvil2";
function App() {
return (
Page title A
Page title B
Page title C
Tab A
Tab B
Tab C
Scope of Tab AScope of Tab BScope of Tab C
);
}
export default App;
```
**Don't**
Don't change content outside of the Tab scope between Tabs.
#### Showing numerical values
Tabs can utilize small [Chips](/docs/web/components/chip/design) to convey value. Pair a Tab with a Chip when the number value is informational in nature.
```tsx lines theme={null}
import { Tab, Flex, Chip } from "@servicetitan/anvil2";
function App() {
return (
All
Foo
Bar
);
}
export default App;
```
**Do**
If a numerical value is relevant, it may be optionally added to a Tab.
```tsx lines theme={null}
import { Tab, Flex, Chip } from "@servicetitan/anvil2";
import { core } from "@servicetitan/anvil2/token";
function App() {
return (
All
Foo
Bar
);
}
export default App;
```
**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](/docs/web/components/alert/design), 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.
```tsx lines theme={null}
import { Tab, Alert } from "@servicetitan/anvil2";
function App() {
return (
<>
Tab A
Tab B
Tab C
Place an Alert below the Tab when its scope is limited to just this
Tab content.
Scope of Tab BScope of Tab C
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Tab, Flex, Alert } from "@servicetitan/anvil2";
function App() {
return (
Place an Alert above the Tabs when its scope is across Tabs.
Tab A
Tab B
Tab C
Scope of Tab AScope of Tab BScope of Tab C
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Tab, Flex, Icon } from "@servicetitan/anvil2";
import { core } from "@servicetitan/anvil2/token";
import Warning from "@servicetitan/anvil2/assets/icons/material/round/warning.svg";
function App() {
return (
Tab A
Tab B
Tab C
);
}
export default App;
```
**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](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-automatic/), 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](/docs/accessibility/changing-content).
