Components

SwitchField

Form field component for toggling between two states.

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`	—	—	`boolean`
`validator`	—	`null`	`function`
`error`	—	`''`	`string`
`required`	—	`false`	`boolean`
`showOptionalLabel`	—	`true`	`boolean`
`optionalLabel`	—	—	`string`
`disabled`	—	`false`	`boolean`
`size`	—	`'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>
    <SwitchField id="field-id">
        <template #label>
            Enable <strong>advanced</strong> mode
        </template>
    </SwitchField>
</template>

Usage

id

Sets the id of the field.

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

Type: string
Required: true

label

Sets the label of the field.

 <template>
    <SwitchField 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>
    <SwitchField legend="Legend text" />
</template>

Type: string

helpText

Sets the help text of the field.

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

Type: string

modelValue

Sets the value of the field.

 <template>
    <SwitchField v-model="isEnabled" />
</template>
<script setup lang="ts">
const isEnabled = ref(false)
</script>

validator

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

Since this field expects a boolean value, the validateBooleanField utility should be used to perform required field validation.

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

Type: string
Default: ''

required

Sets the required state of the field.

 <template>
    <SwitchField 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>
    <SwitchField 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>
    <SwitchField legend="Settings" optionalLabel="(not required)" />
</template>

Type: string

disabled

Sets the disabled state of the field.

 <template>
    <SwitchField disabled />
</template>

Type: boolean
Default: false

size

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

 <template>
    <SwitchField :size="ControlFieldSize.LG" />
</template>

Type: ControlFieldSize
Default: ControlFieldSize.MD

Options

Value	Description
`XS`	xs
`SM`	sm
`MD`	md
`LG`	lg

icon

Sets the icon of the field.

 <template>
    <SwitchField icon="mdi:check" />
</template>

Type: string

styleType

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

 <template>
    <SwitchField :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.
`SUCCESS`	Uses the success color for the background when the switch is on.

fitToContent

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

 <template>
    <SwitchField fitToContent />
</template>

Type: boolean
Default: false

checkboxWrapperClass

Sets additional classes for the checkbox wrapper element.

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

Type: string

labelClass

Sets additional classes for the label element.

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

Type: string