GrCheckboxGroup

core
forms
API · 10 props
⌨ keys

Collects checkboxes into one multi-select field with a shared model and states.

import { GrCheckboxGroup } from '@feugene/granularity/components/GrCheckboxGroup'

Overview

When to take it

several values out of a short set — permissions, tags, days of the week, notification channels;
every option has to be visible — the selection is seen as a whole, without opening a panel;
the group is part of a form — a shared string[] model, shared disabled, readonly and invalid;
there are up to a dozen options — beyond that the list grows longer than the screen.

When to take something else

Need	Take
There are many options	`GrSelect` with `multiple`
There are many options and they are searched by typing	`GrAutocomplete`
Only one can be selected	`GrRadioGroup`
There is a single checkbox	`GrCheckbox`
The options are nested	`GrTreeSelect`

Playground controls come from the API, not from hand

Stage

Loading…

0 changed· state is in the URL

API generated from the package · cannot drift

Props

Prop	Type	default	Description
`disabled`	`boolean \| undefined`	`false`	Disable the whole group. Combined with `disabled` of `GrFormField`.
`options`	`GrCheckboxGroupOption[] \| undefined`	`undefined`	The options from which the group builds the checkboxes. Not needed if the checkboxes are laid out in the slot.
`readonly`	`boolean \| undefined`	`false`	Read-only: the selection is visible but does not change.
`invalid`	`boolean \| undefined`	`false`	The visual and ARIA state of an error for the whole group.
`required`	`boolean \| undefined`	`false`	A required group: `aria-required` is announced by the checkboxes themselves.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| undefined`	`undefined`	The size step of the checkboxes in the group. `md` by default; taken from `GrConfigProvider`.
`ariaLabel`	`string \| undefined`	`undefined`	The accessible name of the group. If not set, the name is taken from the label of `GrFormField`.
`name`	`string \| undefined`	`undefined`	A shared name for a native form: the values leave as repeated fields.
`direction`	`GrCheckboxGroupDirection \| undefined`	`"vertical"`	The layout: `vertical` — in a column, `horizontal` — in a row with wrapping. `vertical` by default.
`modelValue`requiredv-model	`string[]`	—	The checked values (`v-model`): every checkbox in the group has its own `value`.

Slots

Slot	Type	Description
`default`	`any`	Markup of your own for the checkboxes instead of generating them from `options`.

Events

Event	Signature	Description
`update:modelValue`	`(event: "update:modelValue", value: string[]): void`	—
`change`	`(event: "change", value: string[]): void`	—
`focus`	`(event: "focus", event: FocusEvent): void`	—
`blur`	`(event: "blur", event: FocusEvent): void`	—

Methods

Methods	Signature	Description
`focus`	`() => void`	Put focus on the first available checkbox of the group.
`blur`	`() => void`	Remove focus from the first available checkbox — the counterpart of `focus`.

Types

Every exported type of the subpath, grouped by the file it lives in. Names, generics and bodies come from the package’s declaration files and cannot drift.

Import

import type { GrCheckboxGroupConfigurableProps, GrCheckboxGroupDirection, GrCheckboxGroupOption } from '@feugene/granularity/components/GrCheckboxGroup'

Filedist/types/components/GrCheckboxGroup/config.d.ts

grCheckboxGroupConfigconst

const grCheckboxGroupConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrCheckboxGroup">;

Filedist/types/components/GrCheckboxGroup/defaults.d.ts

GrCheckboxGroupConfigurablePropsinterface

interface GrCheckboxGroupConfigurableProps {
    size: GrCheckboxSize;
}

Filedist/types/components/GrCheckboxGroup/GrCheckboxGroup.vue.d.ts

GrCheckboxGroupDirectiontype

type GrCheckboxGroupDirection = 'vertical' | 'horizontal';

GrCheckboxGroupOptioninterface

interface GrCheckboxGroupOption {
    value: string;
    label: string;
    disabled?: boolean;
}

GrCheckboxGroupPropsinterface

interface GrCheckboxGroupProps {
    modelValue: string[];
    options?: GrCheckboxGroupOption[];
    name?: string;
    disabled?: boolean;
    readonly?: boolean;
    invalid?: boolean;
    required?: boolean;
    direction?: GrCheckboxGroupDirection;
    size?: GrCheckboxSize;
    ariaLabel?: string;
}

GrCheckboxGroupEmitsinterface

interface GrCheckboxGroupEmits {
    (e: 'update:modelValue', value: string[]): void;
    (e: 'change', value: string[]): void;
    (e: 'focus', event: FocusEvent): void;
    (e: 'blur', event: FocusEvent): void;
}

Filedist/types/components/GrCheckboxGroup/index.d.ts

GrCheckboxGroupInstancetype

type GrCheckboxGroupInstance = ComponentExposed<typeof GrCheckboxGroupComponent>;

Usage from the library prose

The model and the context

The group hands the nested checkboxes the selected values, name, size and the disabled/readonly/invalid states, so they need no v-model of their own — value is enough:

vue

<GrCheckboxGroup v-model="channels" name="channels" :options="options" />

<GrCheckboxGroup v-model="channels" direction="horizontal">
  <GrCheckbox value="sms">SMS</GrCheckbox>
  <GrCheckbox value="email">Email</GrCheckbox>
</GrCheckboxGroup>

name goes to every checked checkbox, so a native form gets a repeated field: new FormData(form).getAll('channels').

The disabled of an individual option beats an enabled group. A value in the model that is not among the options is not lost by the group: unchecking a neighbouring checkbox keeps it.

The role and ARIA

role="group", not radiogroup: checkboxes have no roving tabindex and no moving of the selection with the arrows — each stays a Tab stop of its own, exactly like a set of native <input type="checkbox">.

role="group" does not support aria-required and aria-readonly (axe reports that as a critical aria-allowed-attr), so both states are declared by the checkboxes themselves. aria-invalid, on the contrary, hangs on the group alone: duplicated on every item, it would make a screen reader repeat “invalid value” as many times as there are checkboxes in the group — on an error the items are merely recoloured.

Being required

As with a single checkbox, required is a declaration; a form rule does the checking. For a group the built-in required works: an empty array counts as an empty value.

const rules: GrFormRules = {
  channels: [{ required: true, message: 'Choose at least one channel' }],
}

GrCheckboxGroup

Overview

When to take it

When to take something else

Playground controls come from the API, not from hand

Examples 4 each with a live demo and its code

Permissions of a role, area by area

A filter with counts

A review that turns into an edit

Days of the week in a row

API generated from the package · cannot drift

Props

Slots

Events

Methods

Types

Usage from the library prose

Overview

When to take it

When to take something else

Playground controls come from the API, not from hand

Examples 4 each with a live demo and its code

API generated from the package · cannot drift

Props

Slots

Events

Methods

Types

Accessibility

Usage from the library prose

Related the fourth question: when not this