# Segmented

> A single choice shown as a row of buttons.

## Examples

### Basic

```vue
<script setup lang="ts">
const view = ref("week");
const views = [
  { label: "Day", value: "day" },
  { label: "Week", value: "week" },
  { label: "Month", value: "month" },
  { label: "Year", value: "year" },
];
</script>

<template>
  <UiSegmented v-model="view" :options="views" label="Calendar view" />
</template>
```

### Icon only

The option labels become the buttons' names.

```vue
<script setup lang="ts">
const style = ref<"bold" | "italic" | "underline">("bold");
const styles = [
  { label: "Bold", value: "bold" },
  { label: "Italic", value: "italic" },
  { label: "Underline", value: "underline" },
] as const;
</script>

<template>
  <UiSegmented v-model="style" :options="[...styles]" label="Text style" size="small" icon-only>
    <template #option="{ option }"><Icon :name="option.value" :size="14" /></template>
  </UiSegmented>
</template>
```

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `SelectOption<T>[]` | `[]` | Segments to render, in order. |
| `label` | `string` | — | Accessible name for the group. |
| `size` | `"medium" \| "small"` | `"medium"` | Size hook, exposed as `data-segmented-size`. |
| `iconOnly` | `boolean` | `false` | Segments render only the `option` slot (e.g. an icon); labels become their accessible names. |
| `disabled` | `boolean` | `false` | Disables every segment. |
| `name` | `string` | — | Form field name: submits the value with a native form, via hidden inputs. |
| `modelValue` | `T` | — | The selected value. |

| Event | Payload | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: T \| undefined]` | `v-model:modelValue` update. |

| Slot | Props | Description |
| --- | --- | --- |
| `option` | `{ option: SelectOption<T>; checked: boolean; }` | Segment content, e.g. an icon. |

Types:

```ts
export interface SelectOption<T extends SelectValue = SelectValue> {
  label: string;
  value: T;
  disabled?: boolean;
}

export type SelectValue = string | number;
```

## Styling

`--ui-indicator-x`, `--ui-indicator-width`, `--ui-indicator-top` and `--ui-indicator-height` place the indicator on the selected item.

- Parts (`[data-part="…"]`): `segmented`, `segmented-indicator`, `segment`
- State attributes: `data-field-name`, `data-segmented-size`, `data-segmented-icon-only`, `data-segmented-sliding`, `data-segmented-animate`, `data-segment-checked`

## Keyboard

| Keys           | Action                             |
| -------------- | ---------------------------------- |
| `Tab`          | Focus the selected segment         |
| Arrow keys     | Select the next / previous segment |
| `Home` / `End` | Select the first / last segment    |

## Accessibility

- The indicator is measured in the browser, so also style `[data-segment-checked]` for the first paint.
- In right-to-left layouts, `←` / `→` follow the visual direction.