Checkbox

KCheckbox is a wrapper for native input type checkbox elements.

Check this out!

<KCheckbox
  v-model="checked"
  label="Check this out!"
/>

Props

v-model

Use v-model to bind the checked state of the underlying <input>. The v-model binds to the modelValue prop of the component and sets current checked state of the input. You can read more about passing values via v-model here.

Unchecked

<KCheckbox v-model="checked">
  {{ checked ? 'Checked!' : 'Unchecked' }}
</KCheckbox>

label

Will place label text to the right of the checkbox. Can also be slotted.

Label example

<KCheckbox
  v-model="checked"
  label="Label example"
/>

labelAttributes

KCheckbox has an instance of KLabel for supporting tooltip text. Use the labelAttributes prop to configure the KLabel's props. This example shows using the labelAttributes to set up a tooltip, see the slot section if you want to slot HTML into the tooltip rather than use plain text.

Tooltip

I use the KLabel `info` prop

Required

<KCheckbox
  v-model="checked1"
  label="Tooltip"
  :label-attributes="{ info: 'I use the KLabel `info` prop' }"
/>

<KCheckbox
  v-model="checked2"
  label="Required"
  :label-attributes="{ required: true }"
/>

description

Will place description text under the checkbox label. Can also be slotted.

Label example

Some description text

<KCheckbox
  v-model="checked"
  label="Label example"
  description="Some description text"
/>

error

Use this prop to apply error styling to the component.

Input error

Some description text

<KCheckbox
 v-model="checked"
 label="Input error"
 error
 description="Some description text"
/>

HTML attributes

Any valid attribute will be added to the input. You can read more about $attrs here.

disabled

Whether or not KCheckbox is enabled.

Can't check this

Can't uncheck this

<KCheckbox v-model="unchecked" label="Can't check this" disabled />
<KCheckbox v-model="checked" label="Can't uncheck this" disabled />

indeterminate

In addition to the checked and unchecked states, a KCheckbox can be in an indeterminate state. The indeterminate state is visual only. The checkbox is still either checked or unchecked as a state, but masks the real value of the checkbox.

<template>
  <KCheckbox
    v-model="checkAll"
    :indeterminate="isIndeterminate"
    :label="checkAll ? 'Uncheck all' : 'Check all'"
    @change="handleIndeterminateChange"
  />
  <KCheckbox
    v-for="(value, index) in indeterminateValues"
    :key="index"
    v-model="value.value"
    :label="value.label"
  />
</template>

<script setup lang="ts">
import { ref, computed, watch } from 'vue'

const checkAll = ref<boolean>(false)

const indeterminateValues = ref<Array<Record<string, any>>>([
  {
    label: 'Option 1',
    value: false,
  },
  {
    label: 'Option 2',
    value: true,
  },
  {
    label: 'Option 3',
    value: false,
  },
])

const isIndeterminate = computed((): boolean => {
  return !!indeterminateValues.value.filter((value) => value.value).length && !!indeterminateValues.value.filter((value) => !value.value).length
})

const handleIndeterminateChange = (value: boolean) => {
  indeterminateValues.value.forEach((val) => {
    val.value = value
  })
}

watch(indeterminateValues, () => {
  // all are selected
  if (indeterminateValues.value.filter((value) => value.value).length === indeterminateValues.value.length) {
    checkAll.value = true
  // all are unselected
  } else if (indeterminateValues.value.filter((value) => !value.value).length === indeterminateValues.value.length) {
    checkAll.value = false
  // some are selected
  } else {
    checkAll.value = false
  }
}, { deep: true })
</script>

Slots

default

Content passed in to the default slot will be shown as the label content. The slot content takes precedence over the label prop.

I agree to the privacy policy.

<KCheckbox v-model="privacyPolicyConsent">
  I agree to the <a :href="privacyPolicyURL">privacy policy</a>.
</KCheckbox>

NOTE

To preserve a valid HTML structure, avoid slotting in block-level elements such as a div into the default slot as it will be rendered inside a label element. This also applies to card-style radio.

description

Content passed in to the description slot will be shown as the description content. The slot content takes precedence over the description prop.

Some label

Anything goes here

<KCheckbox
  v-model="checked"
  description="This will be replaced with a slot"
  label="Some label"
>
  <template #description>
    Anything goes here
  </template>
</KCheckbox>

tooltip

Provides a slot for tooltip content displayed after the checkbox label.

My tooltip

Roses are #FF0000, violets are #0000FF

<KCheckbox v-model="checked">
  My tooltip
  <template #tooltip>Roses are <code>#FF0000</code>, violets are <code>#0000FF</code></template>
</KCheckbox>

Events

KCheckbox emits a few events with same data in payloads.

input

Fired on change, returns the checked status of the checkbox (boolean).

change

Fired on change, returns the checked status of the checkbox (boolean).

update:modelValue

Fired on change, returns the checked status of the checkbox (boolean).