Checkbox

A checkbox is a single yes or no. CheckboxControl is the box, CheckboxIndicator is the mark inside it, and CheckboxContent wraps the box together with its label so the whole row is the hit area.

import { Checkbox, CheckboxContent, CheckboxControl, CheckboxIndicator } from "ropav";

Accept the terms

variant

 primarysecondary

isIndeterminate

isDisabled

isInvalid

<Checkbox>
  <CheckboxContent>
    <CheckboxControl>
      <CheckboxIndicator />
    </CheckboxControl>
    Accept the terms
  </CheckboxContent>
</Checkbox>

Indeterminate

is-indeterminate is the third state, for a checkbox that summarises others: some of the boxes below it are ticked and some are not. It is a display state, not a value — the checkbox is still either selected or not underneath, and clicking it resolves the mixed state one way.

unchecked

checked

mixed

checkbox-indeterminate.vue

<script setup lang="ts">
import { Checkbox, CheckboxContent, CheckboxControl, CheckboxIndicator } from "ropav";
</script>

<template>
  <div class="stack">
    <Checkbox
      v-for="state in ['unchecked', 'checked', 'mixed'] as const"
      :key="state"
      :is-indeterminate="state === 'mixed'"
      :is-selected="state === 'checked'"
    >
      <CheckboxContent>
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        {{ state }}
      </CheckboxContent>
    </Checkbox>
  </div>
</template>

<style scoped>
.stack {
  display: flex;
  flex-direction: column;
  gap: calc(var(--rp-spacing) * 3);
}
</style>

Groups

For several checkboxes that share a name, a validation state and one error message, use a CheckboxGroup.

Accessibility

• The real control is a native <input type="checkbox">, kept in the accessibility tree and out of sight. The box you see is drawn beside it, so the state a screen reader announces is the browser's own.
• CheckboxContent makes the label part of the control, which is what gives the row its hit area — a target far larger than the box, and the reason the label does not need its own handler.

API

Checkbox

Prop	Type	Default	Description
ariaDescribedby	string	—	Ids of the elements that describe the checkbox, on top of any nested help text.
ariaLabel	string	—	Accessible name, for a checkbox with no visible label.
ariaLabelledby	string	—	Ids of the elements that name the checkbox.
defaultSelected	boolean	—	Whether it starts ticked, when uncontrolled.
form	string	—	id of the form to submit with, for a checkbox rendered outside it.
id	string	—	Lands on the hidden input rather than on the wrapper, because the input is the checkbox as far as assistive technology is concerned.
isDisabled	boolean	—	Whether the checkbox is disabled — no interaction, no submission.
isIndeterminate	boolean	—	Shows the mixed state, for a checkbox standing in for a partly selected set.
isInvalid	boolean	—	Whether the value fails validation. Setting it either way takes the field over: false claims the checkbox is valid and shadows validate, the browser and the server alike. Ignored inside a group, which validates on the group's behalf.
isReadOnly	boolean	—	Whether the value can be read but not changed.
isRequired	boolean	—	Whether it has to be ticked for the form to submit.
isSelected	boolean	—	Whether the checkbox is ticked. Makes it controlled, and is ignored inside a group.
name	string	—	Name submitted with the form. Taken from the surrounding group when unset.
validate	ValidationFunction<boolean>	—	Checks the value and returns a message when it is not acceptable.
validationBehavior	"aria" | "native"	"native"	How the checkbox reports validation. Inherited from the surrounding form when unset.
value	string	"on"	Value submitted with the form while the checkbox is ticked, and the value it contributes to a surrounding group's selection.
variant	"primary" | "secondary"	"primary"	Visual variant. Taken from the surrounding group when unset.

The default slot receives:

Slot prop	Type
isDisabled	boolean
isIndeterminate	boolean
isInvalid	boolean
isReadOnly	boolean
isRequired	boolean
isSelected	boolean

Event	Payload
change	boolean
update:isSelected	boolean

CheckboxContent

The default slot receives:

Slot prop	Type
isDisabled	boolean
isFocused	boolean
isFocusVisible	boolean
isHovered	boolean
isIndeterminate	boolean
isInvalid	boolean
isPressed	boolean
isReadOnly	boolean
isRequired	boolean
isSelected	boolean

CheckboxControl

Slots: default.

CheckboxIndicator

The default slot receives:

Slot prop	Type
isDisabled	boolean
isIndeterminate	boolean
isInvalid	boolean
isReadOnly	boolean
isRequired	boolean
isSelected	boolean