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 checked 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.

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
checked
Checked state
boolean false
indeterminate
Indeterminate state. Overrides checked state
boolean false
disabled
Disabled state
boolean false
description
Description - subtext to the label
string null

Events

Name Description
keydown
change
Emits change event
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