Skip to main content

CnSegmentedControl

A switch between a few views of the same thing, such as "My work / My team". One option is always the chosen one.

<template>
<CnSegmentedControl
v-model="view"
aria-label="View"
:options="[
{ value: 'mine', label: 'My work' },
{ value: 'team', label: 'My team', count: 12 },
]" />
</template>

<script>
import { CnSegmentedControl } from '@conduction/nextcloud-vue'

export default {
components: { CnSegmentedControl },
data() { return { view: 'mine' } },
}
</script>

Props​

PropTypeDefaultDescription
optionsArray<string | { value, label, disabled?, count? }>requiredThe options. A plain string is both the value and the label. count shows a number after the label.
modelValuestring | number | booleannullThe value of the chosen option (v-model).
ariaLabelstring''Accessible name of the group.
ariaLabelledbystring''Id of an element that names the group, as an alternative to ariaLabel.
controlsstring''Id of the element the options switch, such as a page view region. Set as aria-controls on every option.
stretchbooleanfalseStretch to the full width, with options of equal width.
phonePillsbooleanfalseUnder 640px, draw the options as separate pills in one row that scrolls sideways, the chosen one filled (PqMobiel's lens chips).
size'normal' | 'compact''normal'compact is the board's period group (34px segments in a 40px track).
mode'radio' | 'toggle''radio'toggle renders buttons with aria-pressed in a group.

Events​

EventPayloadDescription
update:modelValuethe option's valueThe newly chosen option.

Slots​

SlotBindingsDescription
option{ option, checked }Replaces the content of one option.

Accessibility​

  • The control is a radiogroup and each option a radio with aria-checked.
  • Tab enters and leaves the group in one step and lands on the chosen option.
  • Arrow keys move the choice, Home and End jump to the first and last option. Disabled options are passed over.
  • The chosen option has a raised surface and a border, so it does not rest on colour alone.

Segmented control or tabs?​

Use CnSegmentedControl when the choice changes what the same page shows, such as a filter or a scope. Use CnTabs with variant="segmented" when each option has its own panel of content. Both look the same; the tabs keep the tab and panel semantics.

Compact size and toggle mode​

  • size="compact" draws the board's period group: a track with 3px padding, a 2px gap, radius 8px, and segments 34px high (the track is 40px), 14px/600 text with radius 6px. An option with iconOnly: true is 40px wide. normal (the default) is unchanged.
  • mode="toggle" renders plain buttons with aria-pressed in a group instead of a radio group, for a set of presets; Tab visits every button. The default radio mode is unchanged.

Reference​

OpenRegister reliance​

none: this component does not touch OpenRegister, directly or through anything it imports. 0 direct references, 0 files reached through imports.

See the reliance overview for the filterable list.

Props​

NameTypeRequiredDefaultDescription
optionsunion✓—The options. Each is { value, label, disabled?, count? }, or a plain string that is both the value and the label. count shows a number after the label.
modelValueunionnullThe value of the chosen option (v-model).
ariaLabelstring''Accessible name of the group, read out when focus enters it.
ariaLabelledbystring''Id of an element that names the group, as an alternative to ariaLabel.
controlsstring''Id of the element the options switch, such as the region holding a page view's widgets. Set as aria-controls on every option.
sizestring'normal'Size of the control: normal (default) or compact (the board group: 3px track padding, 2px gap, 34px segments).
modestring'radio'radio (default) is a radio group: one option is always chosen and the arrow keys move the choice. toggle is a group of buttons, each with aria-pressed, for a set of presets (the board's period group); Tab visits every button.
stretchbooleanfalseStretch the control to the full width, with options of equal width.
phonePillsbooleanfalseOn a phone (under 640px) draw the options as separate pills in one row that scrolls sideways, the chosen one filled (PqMobiel's lens chips). Wider windows keep the segmented group.

Events​

NamePayloadDescription
update:modelValue—Emitted with the value of the newly chosen option.

Slots​

NameBindingsDescription
optionoption, checkedoption Replaces the content of one option.