KCheckbox link to current page

develop | Release notes

Overview
#

The checkbox is generally used to select one of two possible values in a form.

Layout
#

  • Aligned with container margin
  • When used in a group, vertically stacked
  • Hierarchical nesting is avoided

Guidelines
#

  • Labels should be short and concise
  • Checkbox should not be used to make real-time changes; for this situation, use a KSwitch component instead

States
#

The v-model or checked checkbox state represents an affirmative value.

Checkboxes can also have a "partially-checked" or "indeterminate" state used in cases where the value is neither true nor false, such as when a subset of a topic is selected:

A user cannot enter the indeterminate state by interacting directly with the checkbox; it only occurs due to external interactions.

Example: Label content
#

Label content can be passed via the label property: 

      <KCheckbox label="First lesson" />
In more complex situations, for example when another component is responsible for rendering the label, the default slot can be used: 

      <KCheckbox>
        <KLabeledIcon
          icon="lesson"
          label="First lesson"
        />
      </KCheckbox>
✘ Don't

Don't wrap the default slot's content in <label>:


          <KCheckbox>
            <label>
              <KLabeledIcon
                icon="lesson"
                label="First lesson"
              ></KLabeledIcon>
            </label>
          </KCheckbox>

That would cause two nested <label> elements to be rendered as KCheckbox takes care of it already.

Example: v-model
#

v-model supports array, boolean, number, string, and object.

Array
#

Each value will be added/removed from the selectedGroupIds array based on each checkbox state.

Boolean
#

If checked, isSelected will become true, otherwise false. Note that here, value is not needed.

Number
#

If checked, selectedNumber will be set to value, otherwise null.

String
#

If checked, selectedString will be set to value, otherwise null.

Object
#

If checked, selectedObject will be set to value, otherwise null.

Example: checked
#

As an alternative to v-model, the combination of :checked and @changed can also be used to dynamically update selected choices.

Multiple checkboxes
#

This example achieves the same result as v-model's array example.

Single checkbox
#

This example achieves the same result as v-model's boolean example.

Props
#

Name Description Type Default Required
label
#
Text label
 string null —
labelDir
#
RTL dir of the text label Options: 'auto', 'ltr', 'rtl', null.
 string 'auto' —
showLabel
#
Whether or not to show the label
 boolean true —
v-model
#
Reactive v-model checkbox state. Updates with the change event.
 array|boolean|number|string|object undefined —
checked
#
Legacy API checkbox state. (Note: Use either v-model or checked. If both are passed, v-model takes precedence.)
 boolean false —
indeterminate
#
Indeterminate state. Overrides v-model or checked checkbox state.
 boolean false —
value
#
The value that (1) will be added to the v-model array, or (2) v-model will be set to, when the checkbox is checked.
 number|string|object null —
disabled
#
Disabled state
 boolean false —
description
#
Description - subtext to the label
 string null —
presentational
#
Whether or not the checkbox is presentational. Useful for cases where the checkbox is used as a visual element only, and keyboard focus should be managed by other elements.
 boolean false —

Events
#

Name Description
keydown
#
 —
change
#
Emits change event with the new checkbox state. Used by v-model or legacy API to keep the checkbox state in sync. The original user event that triggered the change (if any) is forwarded as a second argument for legacy API compatibility.
blur
#
Emits blur event, useful for validation.

Slots
#

Name Description
default
#
Optional slot as alternative to label prop

Methods
#

Name Description
focus
#
Sets keyboard focus to the checkbox