Components

TriStateCheckboxField

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

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

Usage

id

Sets the id of the field.

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

Type: string
Required: true

label

Sets the label of the field.

 <template>
    <TriStateCheckboxField 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>
    <TriStateCheckboxField legend="Sample legend" />
</template>

Type: string

helpText

Sets the help text of the field.

 <template>
    <TriStateCheckboxField 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>
    <TriStateCheckboxField 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 checkbox is unchecked.
`CHECKED`	The checkbox is checked.
`INDETERMINATE`	The checkbox is in a partial/mixed state.

validator

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

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

Type: string
Default: ''

disabled

Sets the disabled state of the field.

 <template>
    <TriStateCheckboxField disabled />
</template>

Type: boolean
Default: false

required

Sets the required state of the field.

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

Type: string

size

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

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

Type: ControlFieldSize
Default: ControlFieldSize.MD

Options

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

inverse

Sets the checkbox on the right side of the text.

 <template>
    <TriStateCheckboxField inverse />
</template>

Type: boolean
Default: false