Components

CheckboxField

Checkbox form field used for capturing boolean input, such as toggles or user agreements.

Component

View code

Show playground

Sample legend (optional)

Checkbox label text

Props

Props	Required	Default	Type
`id`	`true`	—	`string`
`label`	—	`'Text'`	`string`
`legend`	—	—	`string`
`helpText`	—	—	`string`
`modelValue`	—	`false`	`boolean`
`validator`	—	`null`	`function`
`error`	—	`''`	`string`
`disabled`	—	`false`	`boolean`
`required`	—	`false`	`boolean`
`showOptionalLabel`	—	`true`	`boolean`
`optionalLabel`	—	—	`string`
`size`	—	`ControlFieldSize.MD`	`ControlFieldSize`
`inverse`	—	`false`	`boolean`

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>
    <CheckboxField id="field-id">
        <template #label>
            I agree to the <a href="/terms" class="underline">Terms of Service</a>
        </template>
    </CheckboxField>
</template>

Usage

id

Sets the id of the field.

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

Type: string
Required: true

label

Sets the label of the field.

 <template>
    <CheckboxField label="Checkbox label text" />
</template>

Type: string
Default: 'Text'

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 of the field.

 <template>
    <CheckboxField legend="Sample legend" />
</template>

Type: string

helpText

Sets the help text of the field.

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

Type: string

modelValue

Sets the value of the field.

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

Type: string
Default: ''

disabled

Sets the disabled state of the field.

 <template>
    <CheckboxField disabled />
</template>

Type: boolean
Default: false

required

Sets the required state of the field.

 <template>
    <CheckboxField 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>
    <CheckboxField legend="Terms" :showOptionalLabel="false" />
</template>

Type: boolean
Default: true

optionalLabel

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

 <template>
    <CheckboxField legend="Terms" optionalLabel="(not required)" />
</template>

Type: string

size

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

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

Type: ControlFieldSize
Default: ControlFieldSize.MD

Options

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

inverse

Sets the checkbox on the right side of the text.

 <template>
    <CheckboxField inverse />
</template>

Type: boolean
Default: false