## Import
```jsx
import { Switcher } from "@cfa/react-core";
```
## Live Editor
```jsx
function Example() {
const apps = [
{ id: "operator-portal", name: "Operator Portal" },
{ id: "team-member-hub", name: "Team Member Hub" },
{ id: "supply-chain", name: "Supply Chain" },
];
return (
{(item) => {item.name}}
);
}
```
## Guidelines
### When to use
- Switcher is for changing the active product context, such as apps, locations, or languages, which changes what the product shows.
### Do
- Use Switcher instead of Select when the choice lives in app chrome, such as the header or side navigation, and is not a form field.
- Show the current selection in the trigger. Include the leading icon when list items use icons.
- Start with label-only options when names are self-explanatory. Add icons, descriptions, or a secondary label, such as a store ID, as options need disambiguation.
- Enable search when the list is too long to scan quickly.
- Keep option labels short and parallel. Use sentence case, such as Operator portal, Team member hub, and Supply chain.
### Avoid
- Mixing action verbs or long dashboard-style names in Switcher, such as View team schedules or Supply chain management dashboard.
- Using Switcher to collect a value in a form. Use Select, Combobox, or RadioGroup.
- Using Switcher for command or action lists. Use Menu.
- Using Switcher for peer content panels on the same page. Use Tabs.
- Using Switcher for on/off or persistent view-mode toggles. Use Switch or ToggleButton.
## Composition
A full app switcher with rich list items (icons and descriptions), a two-column grid layout, and search. Set `textValue` on items with non-plain-text children so selection, filtering, and screen readers work correctly.
```jsx
function AppSwitcherExample() {
const { contains } = useFilter({ sensitivity: "base" });
const apps = [
{
id: "operator-portal",
name: "Operator Portal",
description: "Manage daily restaurant operations and reporting",
Icon: Restaurant,
iconBackground: "var(--ds-semantic-color-background-brand-navy)",
iconColor: "var(--ds-semantic-color-content-knockout)",
},
{
id: "team-member-hub",
name: "Team Member Hub",
description: "Schedules, training, and team resources",
Icon: Store,
iconBackground: "var(--ds-semantic-color-background-brand-red)",
iconColor: "var(--ds-semantic-color-content-knockout)",
},
{
id: "supply-chain",
name: "Supply Chain",
description: "Inventory, ordering, and delivery tracking",
Icon: ChartBar,
iconBackground: "var(--ds-semantic-color-background-brand-orange)",
iconColor: "var(--ds-semantic-color-content-knockout)",
},
{
id: "admin",
name: "Admin Console",
description: "User access, permissions, and org settings",
Icon: Settings,
iconBackground: "var(--ds-semantic-color-background-brand-dark-gray)",
iconColor: "var(--ds-semantic-color-content-knockout)",
},
];
return (
{(item) => (
{item.name}{item.description}
)}
);
}
```
## Storybook
More examples, including trigger sizes, grid layouts, and disabled states, are available in [Storybook](https://ds-react-storybook.vercel-builds.cfadevelop.com/?path=/story/switcher--default).
## Switcher vs Select
Use **Switcher** when the user is switching between apps, workspaces, or contexts — typically in a header or shell, not inside a form field.
Use **Select** when the user is choosing a value as part of a form or settings flow.
| | Switcher | Select |
| --- | --- | --- |
| **Typical use** | App/context navigation | Form fields, filters, settings |
| **Trigger** | Tertiary `Switcher.Trigger` | Form-styled `Select.Button` |
| **Label** | `aria-label` on `Switcher.Root` | `Select.Label` |
| **Popover** | Built into `Switcher.List` | Explicit `Select.Popover` |
| **Selection API** | `value`, `defaultValue`, `onChange` | `value`, `defaultValue`, `onChange` |
| **Multiple selection** | No (single only) | Yes (`selectionMode="multiple"`) |
| **Form support** | No (`name`, validation, `isRequired`, etc. are omitted) | Yes (`Select.Error`, `isInvalid`, native forms) |
| **Built-in layouts** | `layout="stack"` or `layout="grid"` on `Switcher.List` | Manual list layout |
| **Search** | Optional `filter` on `Switcher.List` (with `useFilter`) | Use `Combobox` or `Autocomplete` instead |
If you need sections, a clear button, invalid/required states, or multiple selection, use **Select** (or **Combobox** for typeahead). If you need a compact app switcher with optional grid or search, use **Switcher**.
## Gotchas
- **Accessible name** — There is no `Switcher.Label`. Provide `aria-label` (or `aria-labelledby`) on `Switcher.Root`.
- **Not a form control** — Do not use Switcher for form submission. It does not support `name`, `isRequired`, `isInvalid`, or validation props. Use `Select` for form fields.
- **Selection prop names** — Use `value` / `defaultValue` / `onChange`. Deprecated React Aria aliases such as `selectedKey`, `defaultSelectedKey`, and `onSelectionChange` are not exposed.
- **Composition** — `Switcher.List` renders the popover internally. Do not add `Select.Popover` or a separate popover wrapper.
- **Popover height** — Pass `maxHeight` to `Switcher.List` to override the popover's default 500px maximum height.
- **Search** — Pass a `filter` function from `useFilter` to `Switcher.List`. Set `searchPlaceholder` (and optionally `searchAriaLabel`) when search is enabled.
- **Rich list items** — For non-plain-text children, set `textValue` on `Switcher.Item` so selection, filtering, and screen readers work correctly.
- **Default width** — `Switcher.Root` applies a `min-width` so stack-layout popovers are at least as wide as the trigger and may grow to fit wider list content. Override with `style` or `className` if your layout needs a narrower trigger.
- **Grid layout** — With `layout="grid"`, `Switcher.List` uses the same `ListBox` grid as `ListBox.Root`. `gridColumns` defaults to 2. Override `--list-box-grid-column-width` on the list with the `style` prop to change column width. The popover is at least as wide as the trigger and grows to fit the grid.
## Props
### Switcher.Root
| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| ref | `Ref` | - | Requires React 19. |
| allowsEmptyCollection | `boolean` | - | Whether the select should be allowed to be open when the collection is empty. |
| aria-describedby | `string` | - | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-label | `string` | - | Defines a string value that labels the current element. |
| aria-labelledby | `string` | - | Identifies the element (or elements) that labels the current element. |
| autoComplete | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| autoFocus | `boolean` | - | Whether the element should receive focus on render. |
| children | `ChildrenOrFunction` | - | The children of the component. A function may be provided to alter the children based on component state. |
| className | `ClassNameOrFunction` | `'react-aria-Select'` | The CSS \[className]\(https\://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| defaultOpen | `boolean` | - | Sets the default open state of the menu. |
| defaultValue | `Key \ | null` | - | The default value (uncontrolled). |
| dir | `string` | - | - |
| disabledKeys | `Iterable` | - | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. |
| excludeFromTabOrder | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| form | `string` | - | The \`\