Checkbox

updated

You have a choice. Three, actually. A checkbox with checked, unchecked and indeterminate states.

Demo

Open Props in the corner of the example to try color, size and disabled. color takes Button's colours, primary by default, or one of your own. It fills a checked box and the circle behind it; the edge takes the colour's text shade, which keeps 3:1 against the page where a bright warning fill doesn't, and an unchecked box keeps the --input edge, so a column of empty boxes looks the same whatever their colour. An invalid checkbox still turns red. A CheckboxGroup passes its color to every checkbox in it; one with a color of its own keeps it.

size runs from xs, 14px, to xl, 24px. md, the default, is Material's 18px. The circular state layer grows with the box.

Installation

Usage

<script setup lang="ts">
import { Checkbox } from '@/components/ui/checkbox'
import { Field, FieldLabel } from '@/components/ui/field'

const accepted = ref(false)
</script>

<template>
  <Field orientation="horizontal">
    <Checkbox v-model="accepted" />
    <FieldLabel>Accept terms and conditions</FieldLabel>
  </Field>
</template>

Set name, and it submits with the form. Inside a Field, clicking the label toggles it. On its own, give it an aria-label or a Label.

When checked, the box fills with its colour, --primary by default, and the check draws itself in. Hover or press it, and a soft circle shows up behind the box.

Examples

States

v-model is true, false or 'indeterminate'. The last one is the "it's complicated" state: a "select all" checkbox when only some items are checked. Click it, and it becomes checked.

States

Touch target

Smaller than a finger? Add touch-target: expand when it stands alone, wrapper when it sits close to others. How it works.

With wrapper, the label moves along with the box.

Touch target

Description

Put the label and its description in a FieldContent. The checkbox lines up with the first line of the label, and the description is added to the checkbox's aria-describedby.

Description

A summary of new comments and mentions, once a day.

Group

CheckboxGroup collects the checked values into one array.

Wrap it in a FieldSet with a legend to name it. For a group-wide error like "pick at least one", set invalid on the fieldset, and every checkbox turns red.

Group
Office days

2 of 5 selected

Each checkbox is its own Tab stop, as everywhere else. Want one Tab stop and arrow keys instead? Turn on roving-focus.

variant and orientation lay the options out as cards, a list or a table, in a column or a row. See Choice Group.

Invalid

Invalid
Accept the terms to create an account.

API Reference

class is also accepted and merged over the base classes.

Data attributes

data-slotAttributesDescription
checkboxdata-state, data-color, data-size, data-disabled, data-touch-targetThe checkbox. data-state is checked, unchecked or indeterminate. data-color is its own color, or the group's.
checkbox-groupdata-variant, data-color, data-orientationThe group.

Changelog

  1. registry 0.22.1

    20b5be9 — PageIndicator: each page's pressable area now reaches half the gap past its dot, so the row has no dead space between pages, and a hover or a press lights that area up as a halo, as on Checkbox; the dot itself no longer darkens on hover. touchTarget still grows the area to 48px.

  2. registry 0.22.0

    ac0cc05 — Checkbox, Radio, Switch and Slider no longer declare as and asChild, as Rating already does: Reka's slot cloned the control's own indicator, thumb or track into the root, which left an inert control. The props are gone from their API tables too.

    f29a239 — A row of a disabled RadioGroup or CheckboxGroup, or of a group inside a disabled FieldSet, looks disabled: choice-row drops its hover tint and shows a not-allowed cursor when the row's checkbox or radio is disabled, not only when its Field is, and FieldLabel dims beside a disabled checkbox or radio.

  3. core 0.16.0

    f29a239 — A row of a disabled RadioGroup or CheckboxGroup, or of a group inside a disabled FieldSet, looks disabled: choice-row drops its hover tint and shows a not-allowed cursor when the row's checkbox or radio is disabled, not only when its Field is, and FieldLabel dims beside a disabled checkbox or radio.

  4. registry 0.21.0

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  5. registry 0.13.0

    5a478d3 — Checkbox, Radio, Switch, Slider, Progress, Stepper and TabsList take color: primary (the default), neutral, destructive, success, warning, info, or any name you declare on [data-slot][data-color="<name>"], as on Button. The root carries data-color. Whatever they draw straight on the page takes the colour's --tone-text: a checked edge, the radio's dot, the default slider's range and thumb, the progress bar and the tab line. That keeps a bright success, warning or info at 3:1 against the page. Fills with something on them, like the checked box, the switch track and the active step, keep --tone. On the choice controls the unchecked edge stays --input and an invalid control still turns destructive. Keyboard focus rings a control in a colour other than primary in its --tone-text, red once it's invalid. CheckboxGroup and RadioGroup pass their color to every control in them without one, and ChoiceGroup takes color for the selected card's edge, the focused card's ring and the selected row's tint. Switch, Checkbox, Radio and Slider now set data-size, md by default. They need the @kappa-ui/core release that lets tone-control follow data-color.

    Recoloured Switch, Checkbox, Radio or Slider with class="[--tone:…] [--tone-foreground:…]", as the theming page used to suggest? Their edges and marks now read --tone-text, so add [--tone-text:…] to the class, or use color.

  6. core 0.10.0

    5a478d3 — tone-control works with a color prop. On an element with data-slot and data-color it leaves --tone, --tone-foreground and --tone-text to the [data-slot][data-color] rules, so the control takes that tone, and it keeps --input as the unchecked edge. A colour other than primary also rings the control in its --tone-text. Any other element gets primary exactly as before, now including --tone-text, so copies of Switch, Checkbox, Radio and Slider made before the prop look the same. tone-invalid now turns --tone-text destructive along with the rest of the tone, so edges, marks and rings drawn in it go red on an invalid control too. Copies made before the prop don't read --tone-text, so they look the same. choice-row tints a selected option in its group's tone when the group has data-slot and data-color, and in primary when it doesn't.

  7. registry 0.10.0

    0f38faa — Switch, Checkbox, Radio and Slider take their tone from core's tone-control and tone-invalid utilities instead of a dozen variable assignments each, so they need the @kappa-ui/core release that adds them. They look the same, and a [--tone:…] class still recolours them. Long class strings across the components are now wrapped by variant group.

  8. registry 0.6.0

    4e35ec3 — Card takes size from xs to xl on one --card-spacing (md is the default and replaces default) and variant: outline (unchanged, the default), solid with a small shadow and no border, soft tinted, subtle tinted with a border. ChoiceGroup is the layout behind CheckboxGroup and RadioGroup's variant and orientation, in its own choice-group item; radio-group depends on it instead of on checkbox.