Components

StepSwitch

Standalone switch control with multiple user-defined steps, usable independently or within custom form layouts.

Component

View code

Show playground

Props

Props	Required	Default	Type
`id`	`true`	—	`string`
`ariaLabel`	—	—	`string`
`modelValue`	—	—	`string \| number`
`steps`	—	`[]`	`StepSwitchOption[]`
`maxSteps`	—	`5`	`number`
`disabled`	—	`false`	`boolean`
`size`	—	`ControlFieldSize.MD`	`ControlFieldSize`
`styleType`	—	`SwitchStyle.BRAND`	`SwitchStyle`

Usage

id

Sets the id of the underlying native range input.

 <template>
    <StepSwitch id="my-step-switch" :steps="steps" />
</template>

Type: string
Required: true

ariaLabel

Sets the accessible label of the switch. Use it when there is no visible label. Falls back to Select step.

 <template>
    <StepSwitch id="my-step-switch" :steps="steps" ariaLabel="Effort" />
</template>

Type: string

modelValue

Controls the selected step by its value. Use v-model for two-way binding. If it does not match any step, the first step is shown as selected.

 <template>
    <StepSwitch id="my-step-switch" v-model="effort" :steps="steps" />
</template>
<script setup lang="ts">
const effort = ref<string | number>('medium')
</script>

Type: string | number

steps

Defines the available steps, in order. Each step has a value and an optional label. The label is announced by screen readers as the value text of the selected step.

 <template>
    <StepSwitch id="my-step-switch" v-model="effort" :steps="steps" />
</template>
<script setup lang="ts">
const steps: StepSwitchOption[] = [
    { value: 'low', label: 'Low' },
    { value: 'medium', label: 'Medium' },
    { value: 'high', label: 'High' },
]
</script>

Type: StepSwitchOption[]
Default: []

TypeScript interface

 interface StepSwitchOption {
    value: string | number
    label?: string
}

maxSteps

Sets the maximum number of steps rendered. Extra items in steps are ignored. Keeps the control compact and readable.

Recommended maximum

It is not enforced, but we recommend using no more than 7 steps. Beyond that, the positions become hard to read and to target, especially in small sizes.

 <template>
    <StepSwitch id="my-step-switch" :steps="steps" :maxSteps="4" />
</template>

Type: number
Default: 5

disabled

Sets the disabled state of the switch. When disabled, clicks and keyboard input are ignored and the switch appearance reflects the inactive state.

 <template>
    <StepSwitch id="my-step-switch" :steps="steps" disabled />
</template>

Type: boolean
Default: false

size

Sets the size of the switch. It uses the ControlFieldSize enum.

 <template>
    <StepSwitch id="my-step-switch" :steps="steps" :size="ControlFieldSize.LG" />
</template>

Type: ControlFieldSize
Default: ControlFieldSize.MD

Options

Value	Description
`XS`	Extra Small
`SM`	Small
`MD`	Medium
`LG`	Large

styleType

Sets the style type of the switch. It uses the SwitchStyle enum.

 <template>
    <StepSwitch id="my-step-switch" :steps="steps" :styleType="SwitchStyle.SUCCESS" />
</template>

Type: SwitchStyle
Default: SwitchStyle.BRAND

Options

Value	Description
`BRAND`	Uses the primary brand color for the filled part of the track.
`SUCCESS`	Uses the success color for the filled part of the track.

Emits

Value	Description
`update:modelValue`	Emitted with the `value` of the selected step when the user clicks a step or moves the native range input with the keyboard.

Example

 <template>
    <StepSwitch
        id="my-step-switch"
        :modelValue="effort"
        :steps="steps"
        @update:modelValue="effort = $event"
    />
</template>