Components

StepSwitchField

Switch form field with multiple user-defined steps, such as effort or intensity levels.

Component

View code

Show playground

Example legend (optional)

Effort

Example help text

Props

Props	Required	Default	Type
`id`	`true`	—	`string`
`label`	—	—	`string`
`ariaLabel`	—	—	`string`
`legend`	—	—	`string`
`helpText`	—	—	`string`
`modelValue`	—	—	`string \| number`
`steps`	—	`[]`	`StepSwitchOption[]`
`maxSteps`	—	`5`	`number`
`validator`	—	`null`	`function`
`error`	—	`''`	`string`
`required`	—	`false`	`boolean`
`showOptionalLabel`	—	`true`	`boolean`
`optionalLabel`	—	—	`string`
`disabled`	—	`false`	`boolean`
`size`	—	`ControlFieldSize.MD`	`ControlFieldSize`
`icon`	—	—	`string`
`styleType`	—	`SwitchStyle.BRAND`	`SwitchStyle`
`fitToContent`	—	`false`	`boolean`
`checkboxWrapperClass`	—	—	`string`
`labelClass`	—	—	`string`

Slots

Name	Description
`label`	Overrides the rendered label with custom markup, instead of the plain-text `label` prop. Use this when the label needs formatted or rich content.

 <template>
    <StepSwitchField id="field-id" :steps="steps">
        <template #label>
            Reasoning <strong>effort</strong>
        </template>
    </StepSwitchField>
</template>

Usage

id

Sets the id of the field.

 <template>
    <StepSwitchField id="field-id" :steps="steps" />
</template>

Type: string
Required: true

label

Sets the label of the field.

 <template>
    <StepSwitchField label="Effort" :steps="steps" />
</template>

Type: string

ariaLabel

Sets the accessible label of the switch. Use it when there is no visible label or legend.

 <template>
    <StepSwitchField ariaLabel="Effort" :steps="steps" />
</template>

Type: string

legend

Sets the legend text of the field.

 <template>
    <StepSwitchField legend="Legend text" :steps="steps" />
</template>

Type: string

helpText

Sets the help text of the field.

 <template>
    <StepSwitchField helpText="Help text" :steps="steps" />
</template>

Type: string

modelValue

Controls the selected step by its value. Use v-model for two-way binding.

 <template>
    <StepSwitchField 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>
    <StepSwitchField 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.

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>
    <StepSwitchField :steps="steps" :maxSteps="4" />
</template>

Type: number
Default: 5

validator

Sets the validator function for the field, which controls its internal validation state. It receives the current modelValue.

 <template>
    <StepSwitchField :validator="myValidator" :steps="steps" />
</template>

Type: function
Default: null

error (v-model:error)

Defines the error message displayed by the field. This prop is bindable via v-model:error, allowing two-way syncing of the validation state.

 <template>
    <StepSwitchField v-model:error="errorMessage" :steps="steps" />
</template>

Type: string
Default: ''

required

Sets the required state of the field.

 <template>
    <StepSwitchField required :steps="steps" />
</template>

Type: boolean
Default: false

showOptionalLabel

When the field is not required, shows an "(optional)" hint next to the legend. Set to false to hide it. The hint text defaults to a global setting that can be overridden project-wide, and can also be overridden per field with the optionalLabel prop.

 <template>
    <StepSwitchField legend="Effort" :showOptionalLabel="false" :steps="steps" />
</template>

Type: boolean
Default: true

optionalLabel

Overrides the "(optional)" hint text for this specific field, taking priority over the global default.

 <template>
    <StepSwitchField legend="Effort" optionalLabel="(not required)" :steps="steps" />
</template>

Type: string

disabled

Sets the disabled state of the field.

 <template>
    <StepSwitchField disabled :steps="steps" />
</template>

Type: boolean
Default: false

size

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

 <template>
    <StepSwitchField :size="ControlFieldSize.LG" :steps="steps" />
</template>

Type: ControlFieldSize
Default: ControlFieldSize.MD

Options

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

icon

Sets the icon of the field.

 <template>
    <StepSwitchField icon="mdi:brain" :steps="steps" />
</template>

Type: string

styleType

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

 <template>
    <StepSwitchField :styleType="SwitchStyle.SUCCESS" :steps="steps" />
</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.

fitToContent

When set to true, the field will adjust its width to fit its content, rather than stretching to fill the container.

 <template>
    <StepSwitchField fitToContent :steps="steps" />
</template>

Type: boolean
Default: false

checkboxWrapperClass

Sets additional classes for the switch wrapper element.

 <template>
    <StepSwitchField checkboxWrapperClass="custom-wrapper" :steps="steps" />
</template>

Type: string

labelClass

Sets additional classes for the label element.

 <template>
    <StepSwitchField labelClass="custom-label-class" :steps="steps" />
</template>

Type: string