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.
Before use it, you should install the MazUi plugin in your project, follow instructions in Getting Started
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).
Selected: monthly
<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).
<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 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.
<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
<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.
<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.
<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.
<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.
<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, and a prop on an instance still wins.
app.use(MazUi, {
defaults: {
MazSegmented: { size: 'sm', roundedSize: 'full' },
},
})Accessibility
- The control is a
role="radiogroup"and each segment arole="radio"witharia-checked: assistive technologies announce "Grid view, radio button, 2 of 2". - Name the group with
aria-label, or witharia-labelledbypointing at a visible label. Name icon-only segments with theariaLabelof the option. - Roving tabindex: a single
Tabstop for the whole control, on the selected segment (or the first enabled one when nothing is selected). - Keyboard:
ArrowRightandArrowDownselect the next segment,ArrowLeftandArrowUpthe previous one,HomeandEndthe 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, for a long list of choices MazSelect, and for an independent on/off setting MazSwitch.
Props
| Name | Description | Type | Required | Default | Possible values |
|---|---|---|---|---|---|
| model-value | v-model The value of the selected segment | T | No | - | - |
| options | The segments | MazSegmentedOption<T>[] | Yes | - | - |
| color | Color of the selected segment. Without it, the selected segment is a neutral raised surface | "primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent" | No | - | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'destructive' | 'contrast' | 'transparent' |
| size | Size of the control: same height as the MazBtn of the same size | "xs" | "sm" | "md" | "lg" | "xl" | "mini" | No | 'md' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'mini' |
| rounded-size | Size of the rounded of the control and of its segments | "sm" | "md" | "lg" | "xl" | "none" | "full" | No | 'md' | 'sm' | 'md' | 'lg' | 'xl' | 'none' | 'full' |
| block | Take the full width, the segments share it equally | boolean | No | false | - |
| disabled | Disable the whole control | boolean | No | false | - |
| aria-label | Accessible name of the control | string | No | - | - |
| aria-labelledby | Id of the element that names the control | string | No | - | - |
| id | Id of the control (auto-generated if not provided) | string | No | - | - |
Events
| Event name | Payload | Description |
|---|---|---|
| update:model-value | value: T | Emitted when the selected segment changes |
| change | value: T | Emitted when the selected segment changes |
| update:modelValue | value: T | undefined |
Slots
| Name | Description | Bindings |
|---|---|---|
| item | Content of a segment | option MazSegmentedOption<T>selected boolean |