---
title: "MazSegmented"
description: "MazSegmented is a segmented control to pick one value among a few options, with a sliding indicator, icons, colors and full keyboard navigation. Use it for view modes, filters and settings with two to five choices."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-segmented"
---

# MazSegmented

> MazSegmented is a segmented control to pick one value among a few options, with a sliding indicator, icons, colors and full keyboard navigation. Use it for view modes, filters and settings with two to five choices.

- Package: `maz-ui`
- Import: `import MazSegmented from 'maz-ui/components/MazSegmented'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-segmented

> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)

## Basic usage

Bind the selected value with `v-model` and describe the segments with `options`. Always name the control with `aria-label` (or `aria-labelledby`).

```vue
<script lang="ts" setup>
import MazSegmented from 'maz-ui/components/MazSegmented'
import { ref } from 'vue'

const period = ref('monthly')

const periodOptions = [
  { label: 'Monthly', value: 'monthly' },
  { label: 'Quarterly', value: 'quarterly' },
  { label: 'Yearly', value: 'yearly' },
]
</script>

<template>
  <MazSegmented v-model="period" :options="periodOptions" aria-label="Billing period" />
</template>
```

An option is `{ label?, value, icon?, ariaLabel?, title?, disabled? }`. The `value` can be a string, a number or a boolean, and `v-model` has the same type. The `change` event is emitted with the new value when the user selects a segment.

## Icons

Add an `icon` before the label, or use an icon alone. A segment with an icon only has no text for assistive technologies: **`ariaLabel` is required** on it. Hover hints are not a replacement, but they help sighted users: the `title` of an option shows as a native tooltip (with a keyboard shortcut, for example).

```vue
<script lang="ts" setup>
import { MazComputerDesktop } from '@maz-ui/icons/static/MazComputerDesktop'
import { MazListBullet } from '@maz-ui/icons/static/MazListBullet'
import { MazMoon } from '@maz-ui/icons/static/MazMoon'
import { MazSquares2x2 } from '@maz-ui/icons/static/MazSquares2x2'
import { MazSun } from '@maz-ui/icons/static/MazSun'
import MazSegmented from 'maz-ui/components/MazSegmented'
import { ref } from 'vue'

const view = ref('list')
const theme = ref('auto')

// Icons only: `ariaLabel` names each segment
const viewOptions = [
  { icon: MazListBullet, value: 'list', ariaLabel: 'List view', title: 'List view' },
  { icon: MazSquares2x2, value: 'grid', ariaLabel: 'Grid view', title: 'Grid view' },
]

// Icon + label: the label is the accessible name
const themeOptions = [
  { icon: MazSun, label: 'Light', value: 'light' },
  { icon: MazMoon, label: 'Dark', value: 'dark' },
  { icon: MazComputerDesktop, label: 'Auto', value: 'auto' },
]
</script>

<template>
  <MazSegmented v-model="view" :options="viewOptions" aria-label="Display mode" />
  <MazSegmented v-model="theme" :options="themeOptions" aria-label="Color mode" />
</template>
```

`icon` also accepts an object of [MazIcon](./maz-icon.md) props (`{ icon, size, ... }`) to fine-tune a single icon.

## Colors

Without `color`, the selected segment is a neutral raised surface, like the native segmented controls. With `color`, the selected segment is filled with the color and its `-foreground`.

```vue
<template>
  <!-- Neutral raised segment -->
  <MazSegmented v-model="status" :options="statusOptions" aria-label="Status" />

  <MazSegmented v-model="status" :options="statusOptions" color="primary" aria-label="Status" />
  <MazSegmented v-model="status" :options="statusOptions" color="success" aria-label="Status" />
  <MazSegmented v-model="status" :options="statusOptions" color="destructive" aria-label="Status" />
</template>
```

Available colors: `primary`, `secondary`, `accent`, `info`, `success`, `warning`, `destructive` and `contrast`.

## Sizes

```vue
<template>
  <MazSegmented v-model="value" :options="options" size="mini" aria-label="Mini" />
  <MazSegmented v-model="value" :options="options" size="xs" aria-label="Extra small" />
  <MazSegmented v-model="value" :options="options" size="sm" aria-label="Small" />
  <MazSegmented v-model="value" :options="options" size="md" aria-label="Medium" />
  <MazSegmented v-model="value" :options="options" size="lg" aria-label="Large" />
  <MazSegmented v-model="value" :options="options" size="xl" aria-label="Extra large" />
</template>
```

Each size has the height of the `MazBtn` of the same size, so a segmented control and buttons line up in a toolbar.

## Rounded size

`rounded-size` applies to the control and to its segments: `none`, `sm`, `md` (default), `lg`, `xl` or `full` for a pill.

```vue
<template>
  <MazSegmented v-model="value" :options="options" rounded-size="none" aria-label="Square" />
  <MazSegmented v-model="value" :options="options" rounded-size="xl" aria-label="Extra rounded" />
  <MazSegmented v-model="value" :options="options" rounded-size="full" color="primary" aria-label="Pill" />
</template>
```

## Block

`block` takes the full width of the container, and the segments share it equally. Handy in a dialog, a drawer or a mobile layout.

```vue
<template>
  <div class="max-w-md">
    <MazSegmented v-model="period" :options="periodOptions" block aria-label="Billing period" />
  </div>
</template>
```

## Disabled

`disabled` on the control disables every segment. An option with `disabled: true` disables only that segment: the keyboard navigation skips it.

```vue
<script lang="ts" setup>
import MazSegmented from 'maz-ui/components/MazSegmented'
import { ref } from 'vue'

const plan = ref('pro')

const planOptions = [
  { label: 'Free', value: 'free' },
  { label: 'Pro', value: 'pro' },
  // Not available yet: skipped by the arrow keys
  { label: 'Enterprise', value: 'enterprise', disabled: true },
]
</script>

<template>
  <MazSegmented v-model="plan" :options="planOptions" aria-label="Plan" />

  <!-- The whole control -->
  <MazSegmented v-model="plan" :options="planOptions" disabled aria-label="Plan" />
</template>
```

## Custom segment content

The `item` slot replaces the content of a segment. It receives the `option` and `selected`, so you can show a count, a badge or a different icon for the selected state. Keep it non-interactive: the segment is already a button.

```vue
<script lang="ts" setup>
import MazSegmented from 'maz-ui/components/MazSegmented'
import { ref } from 'vue'

const inbox = ref('all')

const inboxOptions = [
  { label: 'All', value: 'all' },
  { label: 'Unread', value: 'unread' },
  { label: 'Mentions', value: 'mentions' },
]

const counts = { all: 128, unread: 12, mentions: 3 }
</script>

<template>
  <MazSegmented v-model="inbox" :options="inboxOptions" aria-label="Inbox filter">
    <template #item="{ option, selected }">
      <span class="flex items-center gap-1.5">
        {{ option.label }}
        <span
          class="rounded-full px-1.5 text-xs tabular-nums"
          :class="selected ? 'bg-primary text-primary-foreground' : 'bg-foreground/10 text-muted'"
        >
          {{ counts[option.value] }}
        </span>
      </span>
    </template>
  </MazSegmented>
</template>
```

## Global defaults

`size` and `roundedSize` can be set once for every `MazSegmented` through the [global defaults](../guide/global-defaults.md), and a prop on an instance still wins.

```ts
app.use(MazUi, {
  defaults: {
    MazSegmented: { size: 'sm', roundedSize: 'full' },
  },
})
```

## Accessibility

- The control is a `role="radiogroup"` and each segment a `role="radio"` with `aria-checked`: assistive technologies announce "Grid view, radio button, 2 of 2".
- Name the group with `aria-label`, or with `aria-labelledby` pointing at a visible label. Name icon-only segments with the `ariaLabel` of the option.
- Roving tabindex: a single `Tab` stop for the whole control, on the selected segment (or the first enabled one when nothing is selected).
- Keyboard: `ArrowRight` and `ArrowDown` select the next segment, `ArrowLeft` and `ArrowUp` the previous one, `Home` and `End` the first and the last. Arrows are mirrored in right-to-left languages. Moving the focus selects the segment, like a native radio group, and wraps around at the ends.
- Disabled segments are skipped by the keyboard and keep `disabled`.
- The sliding indicator is decorative (`aria-hidden`), and the selected state does not rely on the color alone: the selected segment is also raised or filled.
- Use it for two to five short choices that apply immediately. For navigation between panels use [MazTabs](./maz-tabs.md), for a long list of choices [MazSelect](./maz-select.md), and for an independent on/off setting [MazSwitch](./maz-switch.md).

## MazSegmented API

`import MazSegmented from 'maz-ui/components/MazSegmented'`

### Props

- `model-value` (`T`, `v-model`): The value of the selected segment.
- `options` (`MazSegmentedOption<T>[]`, required): The segments.
- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`): Color of the selected segment. Without it, the selected segment is a neutral raised surface.
- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): Size of the control: same height as the `MazBtn` of the same size.
- `rounded-size` (`"sm" | "md" | "lg" | "xl" | "none" | "full"`, default: `'md'`): Size of the rounded of the control and of its segments.
- `block` (`boolean`, default: `false`): Take the full width, the segments share it equally.
- `disabled` (`boolean`, default: `false`): Disable the whole control.
- `aria-label` (`string`): Accessible name of the control.
- `aria-labelledby` (`string`): Id of the element that names the control.
- `id` (`string`): Id of the control (auto-generated if not provided).

### Events

- `@update:model-value` (payload: `value: T`): Emitted when the selected segment changes
- `@change` (payload: `value: T`): Emitted when the selected segment changes
- `@update:modelValue` (payload: `value: T | undefined`)

### Slots

- `#item`: Content of a segment Bindings: `option: MazSegmentedOption<T>`, `selected: boolean`.
