CheckboxGroup

A checkbox group gathers Checkboxes that answer the same question: they submit under one name, they are validated together, and one error message covers them all. Checkboxes that happen to sit near each other but mean unrelated things are not a group — leave them separate.

import { Checkbox, CheckboxGroup, Description, FieldError, Label } from "ropav";

Interests

Coding

Design

variant

 primarysecondary

isDisabled

isReadOnly

isRequired

isInvalid

<CheckboxGroup name="interests">
  <Label>Interests</Label>
  <Checkbox value="coding">
    <CheckboxContent>
      <CheckboxControl>
        <CheckboxIndicator />
      </CheckboxControl>
      Coding
    </CheckboxContent>
  </Checkbox>
  <Checkbox value="design">
    <CheckboxContent>
      <CheckboxControl>
        <CheckboxIndicator />
      </CheckboxControl>
      Design
    </CheckboxContent>
  </Checkbox>
</CheckboxGroup>

The group's value is an array of the selected checkboxes' value strings. v-model:value hands it to the caller, and default-value just starts it somewhere.

InterestsChoose all that apply.

Coding

Design

Writing

checkbox-group-basic.vue

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

const interests = [
  { label: "Coding", value: "coding" },
  { label: "Design", value: "design" },
  { label: "Writing", value: "writing" },
] as const;
</script>

<template>
  <CheckboxGroup class="group" :default-value="['coding']" name="interests">
    <Label>Interests</Label>
    <Description>Choose all that apply.</Description>

    <Checkbox v-for="interest in interests" :key="interest.value" :value="interest.value">
      <CheckboxContent>
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        {{ interest.label }}
      </CheckboxContent>
    </Checkbox>
  </CheckboxGroup>
</template>

<style scoped>
.group {
  width: 100%;
  max-width: var(--rp-container-md);
}
</style>

Validation

is-required means at least one box has to be ticked, and validate runs against the whole array so a rule like "pick no more than three" has something to read. is-invalid set either way takes the group over: true marks it invalid whatever validate says, and false claims it is valid and shadows validate — the browser and the server alike.

validation-behavior decides when the message appears, and is inherited from the surrounding Form unless the group sets its own.

Accessibility

• The group is a role="group" named by its Label, so a reader entering it is told what the boxes have in common before hearing the first one.
• The error belongs to the group, not to a box. A FieldError inside the group is pointed at by every checkbox in it, which is what stops the same message being read three times over.
• is-disabled and is-read-only on the group apply to every checkbox in it. The difference matters to a reader: a disabled group is skipped, a read-only one is announced and can be reached.
• A checkbox can still disable itself inside an enabled group, which is the case for an option that is unavailable for its own reasons.

API

Prop	Type	Default	Description
ariaDescribedby	string	—	Ids of the elements that describe the group, on top of any nested help text.
ariaLabel	string	—	Accessible name, for a group with no visible label.
ariaLabelledby	string	—	Ids of the elements that name the group.
defaultValue	string[]	—	Values selected to begin with, when the group is uncontrolled.
form	string	—	id of the form to submit with, for a group rendered outside it.
isDisabled	boolean	—	Disables every checkbox in the group.
isInvalid	boolean	—	Whether the group fails validation. Setting it either way takes the group over: false claims it is valid and shadows validate, the browser and the server alike.
isReadOnly	boolean	—	Lets the group be read but not changed.
isRequired	boolean	—	Whether at least one checkbox has to be selected for the form to submit.
name	string	—	Name every checkbox submits under, and the key server errors arrive on.
validate	ValidationFunction<string[]>	—	Checks the selected values and returns a message when they are not acceptable.
validationBehavior	"aria" | "native"	"native"	How the group reports validation. Inherited from the surrounding form when unset.
value	string[]	—	Selected values. Makes the group controlled.
variant	"primary" | "secondary"	"primary"	Variant the checkboxes inside take unless they name their own.

The default slot receives:

Slot prop	Type
isDisabled	boolean
isInvalid	boolean
isReadOnly	boolean
isRequired	boolean
value	string[]

Event	Payload
change	string[]
update:value	string[]