# p-segmented-control

The `p-segmented-control` component is similar to the native `select` element while showing all available options right away.

It even behaves like a `select` where it can be controlled by setting the current value. However, it is not required and you could purely rely on the change event.

By default the `p-segmented-control` displays all options in **equal** size based on its largest option. If the `no-wrap` property is set to `true`, the items will be rendered inline (shrinked to their initial size) with an optional scroller.

Each option needs to be rendered by using a `p-segmented-control-item` child component where the `value` property is **mandatory** in order to emit a useful change event.

## Usage

### Do:

- Use to present a set of selectable options at once.
- Use it for selecting from 2-5 short, consistent options.
- Use them over other selection controls to reduce cognitive load.
- Pair options with icons to improve visual recognition.
- Use icons only when the context meaning is really clear.
- Use preselection when the result is visible by default.
- Use with no selection when a selection by the user is necessary to show the result.
- Use it with a short indication for the unit (such as km, €, %, or $) when possible.
- Use for horizontal and/or vertical display of options.

### Don't:

- Don't use it to filter or navigate content (use [Tabs](../p-tabs/p-tabs.md) instead).
- Don't use it for more than 5 options (use the [Select](../p-select/p-select.md) component).
- Don't use it with mixed values (use [Radio Group](../p-radio-group/p-radio-group.md) or [Select](../p-select/p-select.md) instead).
- Don't exceed maximum width so the values turn multiline.

---

## Related components

- [Select](../p-select/p-select.md)
- [Radio Button](../p-radio-group/p-radio-group.md)
- [Tabs](../p-tabs/p-tabs.md)

## Accessibility support

### Keyboard

| Key / state | Function |
| --- | --- |
| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
| `Space`, `Enter` | Activates the control. |

### ARIA enhancements

#### External **ARIA** provided by the `aria` property:

| ARIA | Usage |
| --- | --- |
| `aria-label="STRING"` | Defines a string value that labels the control item itself. |

#### Internal **ARIA** that is managed by the component:

| ARIA | Usage |
| --- | --- |
| `role="group"` | Identifies a set of user interface objects. |
| `aria-pressed="BOOLEAN"` | Provides the current state of the control. |
| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
| `aria-hidden="true"` | If `required` attribute is set, the visible asterisk indicator is hidden from assistive technologies. |
| `aria-invalid="true"` | If `error` state is set. |
| `aria-required="true"` | Indicates if the element is required. |
| `aria-description="STRING"` | Provides additional content for states. |

## Development considerations

### Labelling

Provide a descriptive `label` on the wrapper component to give context for the group of options. If a more detailed label is needed for each **control item**, use the `aria` property on the control item itself, e.g.: `<p-segmented-control-item value="xs" aria="{ 'aria-label': 'Size x-small' }">XS</p-segmented-control-item>`.

If an **icon only** is used, it is mandatory to also provide an accessible name through the `aria` property of the control item.

### Disabled state

In general, avoid using the `disabled` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.

### Common do's and don'ts

- **Do** provide a clear group `label` that describes the choice being made.
- **Do** pass item-level ARIA through the `aria` prop on `p-segmented-control-item`, especially for icon-only items.
- **Do** use the component state/message API so validation and status changes are announced.
- **Don't** add native `aria-*` attributes directly on the component host.
- **Don't** use `hide-label` without an accessible name.

## Integration examples

See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.

## API

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `'auto'` `1` `2` `3` `4` `5` `6` `7` `8` `9` `10` `11` `12` `13` `14` `15` `16` `17` `18` `19` `20` `21` `22` `23` `24` `25`<br>`BreakpointCustomizable<SegmentedControlColumns>` | `'auto'` | Sets the number of equal-width columns for the item layout. Use `auto` to distribute items based on their content width. Supports responsive breakpoint values. |
| `compact` | `boolean` | `false` | Reduces the item height and spacing for use in dense layouts where vertical space is limited. |
| `description` | `string` | `''` | Sets a supplementary description displayed below the label to give users additional context about the segmented control. |
| `disabled` | `boolean` | `false` | Prevents user interaction with all items in the segmented control and excludes the value from form submissions. |
| `form` | `string` | `undefined` | Associates the segmented control with a form element by its ID when it is not a direct descendant of that form. |
| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
| `label` | `string` | `''` | Sets the visible label text displayed above the segmented control to describe the group of options. |
| `message` | `string` | `''` | Sets the validation feedback message displayed below the segmented control when `state` is `success` or `error`. |
| `name` | `string` | `undefined` | Sets the name of the control submitted with the form data to identify the selected value on the server. |
| `noWrap` | `boolean` | `false` | Prevents items from wrapping to new rows and renders them in a single horizontally scrollable row instead. |
| `required` | `boolean` | `false` | Marks the segmented control as required so the form cannot be submitted until one option is selected. |
| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the segmented control, controlling its visual appearance and feedback message style (`none`, `success`, `error`). |
| `value` | `string | number | null` | `undefined` | Sets the currently selected item's value and pre-selects the matching option when the component renders. Matches an item strictly by type and value, meaning string or number only match an item whose value has the same type and equal value. Use undefined or null for no preselection. Please note that FormData always serializes values as strings, so when participating in a native (uncontrolled) form a number value is restored as string via formStateRestoreCallback and will no longer strictly match a number-typed item. This limitation only applies to native form state restoration; in controlled forms (where the consumer manages value directly via the change event), the number type is preserved end-to-end. |

### Events

| Event | Type | Description |
| --- | --- | --- |
| `blur` | `CustomEvent<void>` | Emitted when the segmented control loses focus, useful for triggering validation on blur. |
| `change` | `CustomEvent<SegmentedControlChangeEventDetail>`<br>`{ value: string | number }` | Emitted when the user selects a different item, carrying the new value in the event detail. |

### Controlled properties

- `value` — a controlled prop, but the component also updates it internally. Listen for the `change` event to observe changes; you do not have to write the value back.

### Slots

| Slot | Required | Allowed tag names | Description |
| --- | --- | --- | --- |
| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
| `description` | no | — | Shows a description. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
| _(default)_ | no | — | Default slot for the `p-segmented-control-item` tags. |
| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |

## Sub-components

These tags are only valid inside the parent(s) listed under each one — often this component, but some are shared and list a different parent (e.g. a tag documented here via a common ancestor). Their APIs come from the same authoritative `component-meta` as the parent above.

### `p-segmented-control-item`

Allowed parent: `p-segmented-control`.

#### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria` | `SegmentedControlItemAriaAttribute` | `undefined` | Sets ARIA attributes on the item's button element to improve accessibility for screen readers. |
| `disabled` | `boolean` | `false` | Prevents this item from being selected and visually dims it; the parent's value will not change to this item's value. |
| `icon` | `''`<br>one of 294 icon names — see [icon names](references/icons.md) | `undefined` | Sets an icon rendered inside the item button using an icon name from the PDS icon library. |
| `iconSource` | `string` | `undefined` | Sets a URL to a custom SVG icon for the item button, overriding the built-in icon set. |
| `label` | `string` | `undefined` | Sets a visible text label rendered inside the item button, used when no slotted content is provided. |
| `value` _(required)_ | `string | number` | `undefined` | Sets the value emitted by the parent `p-segmented-control` when this item is selected. This property is*required**. |

#### Slots

| Slot | Required | Allowed tag names | Description |
| --- | --- | --- | --- |
| _(default)_ | no | — | Default slot for the content. |

## Examples

| Example | When to use | File |
| --- | --- | --- |
| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
| Form | The `p-segmented-control` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.ts](./examples/Form.ts) |
| With Labels | Additional meta information can be displayed by setting a `label` on each child. | [./examples/WithLabels.ts](./examples/WithLabels.ts) |
| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.ts](./examples/Slots.ts) |