## Anatomy
The Segmented Control has three elements that work together to switch the presentation view of current or filtered content.
1. Selected segment
2. Icon
3. Label
## Options
The Segmented Control supports multiple sizes, fill options, and icon configurations for different use cases.
### Sizes
```tsx lines theme={null}
import { SegmentedControl, Flex } from "@servicetitan/anvil2";
function App() {
return (
Level 1
Level 2
Level 3
Level 4
Level 1
Level 2
Level 3
Level 4
);
}
export default App;
```
### Fill
By default, Segmented Control will hug its content. But it can also fill available width.
```tsx lines theme={null}
import { SegmentedControl } from "@servicetitan/anvil2";
function App() {
return (
Level 1
Level 2
Level 3
Level 4
);
}
export default App;
```
### Icons
```tsx lines theme={null}
import { SegmentedControl, Flex, Tooltip } from "@servicetitan/anvil2";
import List from "@servicetitan/anvil2/assets/icons/material/round/list.svg";
import GridView from "@servicetitan/anvil2/assets/icons/material/round/grid_view.svg";
function App() {
return (
List
Grid
ListGrid
);
}
export default App;
```
Place icons before the segment's text label, or use them to replace the text label as an icon-only segment.
Use icon-only segments with Tooltip to provide an accessible label.
## Behavior
The Segmented Control responds to user interaction with distinct visual states and selection behaviors.
### Visual States
#### Default
Default segments do not have a focus-visible state because only the selected segment receives focus.
```tsx lines theme={null}
import { SegmentedControl, Flex } from "@servicetitan/anvil2";
function App() {
return (
Selected
Default
Selected
Default Hover
Selected
Default Active
);
}
export default App;
```
#### Selected
Selected segments do not have hover or active states because users cannot interact with them when selected.
```tsx lines theme={null}
import { SegmentedControl, Flex } from "@servicetitan/anvil2";
function App() {
return (
Selected Default{" "}
Other Segment
Selected Focus Visible
Other Segment
);
}
export default App;
```
* Only one segment remains selected at all times
* At least one segment remains selected at all times
### Focused
Only the selected segment receives focus.
## Usage Guidelines
Use the Segmented Control when switching the presentation view of current or filtered content.
### When to Use
Use Segmented Control for 2-5 selections. Currently it lacks native overflow handling, so test for mobile responsiveness when using this component.
### Alternatives
#### Segmented Control vs Radio
Radios are form controls that users must explicitly submit. Use Segmented Controls for selections that affect the UI immediately.
#### Segmented Control vs Tab
Segmented Control allows users to change the presentation format of displayed content or to filter it. Tabs change the view to show new content.
### How to Use
#### Switching presentation mode
Use Segmented Control to toggle between different presentation modes such as grid vs list.
```tsx lines theme={null}
import { SegmentedControl, Flex, Grid, Card } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [mode, setMode] = useState("grid");
return (
setMode(value)}
>
GridList
{["Bicycle", "Bus", "Car", "Train", "Motorcycle", "Subway"].map(
(name, i) => (
{name}
),
)}
);
}
export default App;
```
#### Filtering content
Use Segmented Control to filter data into segments, providing users with a smaller set of data to engage. Including a number helps indicate how many items are in each filtered segment.
```tsx lines theme={null}
import { SegmentedControl, Flex, Grid, Card } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [filter, setFilter] = useState("all");
return (
setFilter(value)}
>
All
Public
Personal
{filter === "personal"
? ["Bicycle", "Car", "Motorcycle"].map((name, i) => (
{name}
))
: filter === "public"
? ["Bus", "Train", "Subway"].map((name, i) => (
{name}
))
: ["Bicycle", "Bus", "Car", "Train", "Motorcycle", "Subway"].map(
(name, i) => {name},
)}
);
}
export default App;
```
#### Sorting content
Use Segmented Control to allow users to sort a list or display by different criteria (e.g., "Newest," "Oldest," "Most Popular," "Alphabetical"). The core content remains the same, but its order changes.
```tsx lines theme={null}
import { SegmentedControl, Flex } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [, setFilter] = useState("all");
return (
setFilter(value)}
>
Latest
Trending
Saved
);
}
export default App;
```
#### Switching Data Granularity/Time Ranges
Use Segmented Control to toggle between different temporal views of the same data or different interpretations of the same data. Another example includes switching between a percentage (%) or dollar amount (\$).
```tsx lines theme={null}
import { SegmentedControl, Flex } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [, setFilter] = useState("all");
return (
setFilter(value)}
>
DayWeekMonthYear
);
}
export default App;
```
#### Toggling Sub-Categories
Use Segmented Control when a section has closely related, but distinct, sub-sections.
```tsx lines theme={null}
import { SegmentedControl, Flex } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [, setFilter] = useState("all");
return (
setFilter(value)}
>
All
On Hold
Needs Review
Reviewed
);
}
export default App;
```
#### Selecting an Option in a Form
Use Segmented Control for a small number of mutually exclusive choices within a form. It provides a visually appealing and efficient alternative to traditional radio buttons, especially when space is a concern.
```tsx lines theme={null}
import { SegmentedControl, Flex } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [, setFilter] = useState("all");
return (
setFilter(value)}
>
Small
Medium
Large
);
}
export default App;
```
## Content
Use labels and icons to clearly communicate each segment option.
## Keyboard Interaction
Users can navigate the Segmented Control using standard keyboard controls.
| Key | Interaction |
| ----------- | ----------------------------------------------- |
| Arrow Right | While focused, selects the Segment on the right |
| Arrow Left | While focused, selects the Segment on the left |
### Accessibility
* Icon-only segments require an accessible name via `aria-label` or `aria-describedby`.
For more guidance on form field labels and context, see [input field context association best practices](/docs/accessibility/labels-and-ctas#input-field-context-association).
