# MozSegmentedControl
`moz-segmented-control` lets users select one option from a few related choices, displayed as connected buttons. Each option is a `moz-segmented-control-item`, which wraps `moz-button`.
```html story
```
## Code
The source for `moz-segmented-control` and `moz-segmented-control-item` can be found under [toolkit/content/widgets/moz-segmented-control/](https://searchfox.org/firefox-main/source/toolkit/content/widgets/moz-segmented-control/). You can find examples of `moz-segmented-control` in use in the Firefox codebase in both the [print dialog](https://searchfox.org/firefox-main/source/toolkit/components/printing/content/print.html) and [about:addons](https://searchfox.org/firefox-main/source/toolkit/mozapps/extensions/content/components/aboutaddons-themes-mode.mjs).
## When to use `moz-segmented-control`
* Use a segmented control when you want users to pick one option from a small set of closely related options, such as a view mode or a sort order.
* Use a segmented control over a radio group when space is limited and the options have short labels or can be represented by icons.
* Use a segmented control to switch between views when it is paired with a `named-deck`.
## When not to use `moz-segmented-control`
* If there are more than a handful of options or the labels are long, use `moz-radio-group` or `moz-select`.
* If it should be possible for the user to select multiple options, use `moz-checkbox`.
* If the options are actions rather than a choice between states, use `moz-button-group`.
## How to use `moz-segmented-control`
### Importing the element
Like other custom elements, `moz-segmented-control` and `moz-segmented-control-item` are usually lazy loaded when first used. See [Using new design system components](https://firefox-source-docs.mozilla.org/browser/components/storybook/docs/README.reusable-widgets.stories.html#using-new-design-system-components) for more information.
### Combining `moz-segmented-control-item` and `moz-segmented-control`
Place each `moz-segmented-control-item` directly inside `moz-segmented-control`. Do not wrap items in layout elements. The group provides positioning and spacing for its items.
If you are using the elements improperly you may see the following console error:
```sh
moz-segmented-control-item should only be used in an element that extends SelectControlBaseElement.
```
### Setting `value` for the group
The `value` property or attribute of `moz-segmented-control` can be used to set the `checked` state of its `moz-segmented-control-item` elements. While it is also possible to set `checked` directly on individual items, in most cases it's clearer to set `value` on the group. This allows `moz-segmented-control` to serve as the single source of truth for the selected state of its items.
```html
```
```html story
```
### Handling selection changes
When the user selects a different item, that item emits `input` and `change` events. Both events bubble to the group, so they can be handled there:
```js
document.querySelector("moz-segmented-control").addEventListener("change", e => {
console.log(e.target.value);
});
```
### Setting `name` for the group
Set `name` on the containing `moz-segmented-control` to associate its items. The group copies the name to each `moz-segmented-control-item`.
### Setting an accessible name for the group
`moz-segmented-control` is not designed to render a visible label. Use `aria-label` to give the group an accessible name, and rely on the surrounding UI, such as a heading or a `moz-fieldset`, when a visible label is needed:
```html
```
```html story
```
### Setting icons on items
Use the `iconSrc` property or `iconsrc` attribute to show an icon before the item's label:
```html
```
```html story
```
Items can also be icon-only. In that case, omit the `label` and set `aria-label` so the item still has an accessible name:
```html
```
```html story
```
### Setting the `size`
`moz-segmented-control-item` supports the same `size` values as `moz-button`. Set `size="small"` on each item for a more compact control:
```html
```
```html story
```
### Setting the `disabled` state
The `disabled` state can be set on `moz-segmented-control` to disable all of its child items:
```html
```
```html story
```
`disabled` can also be set on individual `moz-segmented-control-item` elements to control their state independently of the rest of the group:
```html
```
```html story
```
The one caveat to this is that it is not possible to programmatically enable an individual item when the containing group is `disabled`.
### Switching views with `named-deck`
Set the `deck` attribute to the `id` of a `named-deck` element to use `moz-segmented-control` as a tab switcher. Selecting an item shows the deck view whose `name` matches the item's `value`, and changing the deck's selected view updates the control. When `deck` is set, the control is exposed to assistive technologies as a tablist rather than a radio group.
```html
```
```html story
```
### Fluent usage
The `aria-label` property of `moz-segmented-control` and the `label` and `aria-label` properties of `moz-segmented-control-item` will generally be provided via [Fluent attributes](https://mozilla-l10n.github.io/localizer-documentation/tools/fluent/basic_syntax.html#attributes). `data-l10n-attrs` are set automatically, so to get things working you just need to supply a `data-l10n-id` as you would with any other element.
For example the following Fluent messages:
```
moz-segmented-control-id =
.aria-label = This is the accessible name for the group
first-item-id =
.label = This is the label for the first item
second-item-id =
.aria-label = This is the accessible name for an icon-only item
```
Would be used to set labels on the different elements as follows:
```html
```