Components

TriStateSwitchField

Switch form field supporting an indeterminate state, in addition to checked and unchecked.

Component

View code

Show playground

Example legend (optional)

Switch label text

Props

Props	Required	Default	Type
`id`	`true`	—	`string`
`label`	—	—	`string`
`legend`	—	—	`string`
`helpText`	—	—	`string`
`modelValue`	—	`TriStateValue.UNCHECKED`	`TriStateValue`
`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>
    <TriStateSwitchField id="field-id">
        <template #label>
            Enable <strong>advanced</strong> mode
        </template>
    </TriStateSwitchField>
</template>

Usage

id

Sets the id of the field.

 <template>
    <TriStateSwitchField id="field-id" />
</template>

Type: string
Required: true

label

Sets the label of the field.

 <template>
    <TriStateSwitchField label="Switch label text" />
</template>

Type: string

Rich label content

The `label` prop is rendered as plain text. For formatted or markup content, use the `label` slot instead (see Slots below).

legend

Sets the legend text of the field.

 <template>
    <TriStateSwitchField legend="Legend text" />
</template>

Type: string

helpText

Sets the help text of the field.

 <template>
    <TriStateSwitchField helpText="Help text" />
</template>

Type: string

modelValue

Controls the state of the field. Use v-model for two-way binding. It uses the TriStateValue enum.

Clicking or pressing space always resolves to TriStateValue.CHECKED or TriStateValue.UNCHECKED. TriStateValue.INDETERMINATE can only be set programmatically.

 <template>
    <TriStateSwitchField v-model="state" />
</template>
<script setup lang="ts">
const state = ref<TriStateValue>(TriStateValue.INDETERMINATE)
</script>

Type: TriStateValue
Default: TriStateValue.UNCHECKED

Options

Value	Description
`UNCHECKED`	The switch is off.
`CHECKED`	The switch is on.
`INDETERMINATE`	The switch is in a partial/mixed state.

validator

Sets the validator function for the field, which controls its internal validation state.

 <template>
    <TriStateSwitchField :validator="myValidator" />
</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>
    <TriStateSwitchField v-model:error="Error message" />
</template>

Type: string
Default: ''

required

Sets the required state of the field.

 <template>
    <TriStateSwitchField required />
</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>
    <TriStateSwitchField legend="Settings" :showOptionalLabel="false" />
</template>

Type: boolean
Default: true

optionalLabel

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

 <template>
    <TriStateSwitchField legend="Settings" optionalLabel="(not required)" />
</template>

Type: string

disabled

Sets the disabled state of the field.

 <template>
    <TriStateSwitchField disabled />
</template>

Type: boolean
Default: false

size

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

 <template>
    <TriStateSwitchField :size="ControlFieldSize.LG" />
</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>
    <TriStateSwitchField icon="mdi:check" />
</template>

Type: string

styleType

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

 <template>
    <TriStateSwitchField :styleType="SwitchStyle.SUCCESS" />
</template>

Type: SwitchStyle
Default: SwitchStyle.BRAND

Options

Value	Description
`BRAND`	Uses the primary brand color for the background when the switch is on or indeterminate.
`SUCCESS`	Uses the success color for the background when the switch is on or indeterminate.

fitToContent

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

 <template>
    <TriStateSwitchField fitToContent />
</template>

Type: boolean
Default: false

checkboxWrapperClass

Sets additional classes for the checkbox wrapper element.

 <template>
    <TriStateSwitchField checkboxWrapperClass="custom-checkbox-wrapper" />
</template>

Type: string

labelClass

Sets additional classes for the label element.

 <template>
    <TriStateSwitchField labelClass="custom-label-class" />
</template>

Type: string