Add CheckboxGroup component

[devongovett]

🙋 Feature Request

We have a Checkbox component already, but it would be nice to support a CheckboxGroup component to more easily create a group of checkboxes, similar to RadioGroup. It should support labeling the entire group of checkboxes, along with controlling the selection state of the checkboxes as a group rather than individually.

💁 Possible Solution

API should be similar to RadioGroup. The value prop could accept an array of values, matching the value prop on each individual Checkbox. Many other props can be applied to the group and propagate to each individual checkbox (e.g. disabled/readonly state, validation state, etc.).

import {ValueBase, InputBase, Validation, LabelableProps} from '@react-types/shared';

interface CheckboxGroupProps extends ValueBase<string[]>, InputBase, Validation, LabelableProps {
  /** Name for the checkboxes when submitting via HTML form. Applies to all checkboxes automatically. */
  name?: string
}

interface CheckboxGroupState {
  /** Current selected values. */
  value: string[],
  /** Sets the selected values. */
  setValue(value: string[]): void,
  /** Adds a value to the set of selected values. */
  addValue(value: string): void,
  /** Removes a value from the set of selected values. */
  removeValue(value: string): void,
  /** Toggles a value in the set of selected values. */
  toggleValue(value: string): void
}

declare function useCheckboxGroupState(props: CheckboxGroupProps): CheckboxGroupState;

interface CheckboxGroupAria {
  /** Props for the checkbox group label element. */
  labelProps: HTMLAttributes<HTMLElement>,
  /** Props for the group element */
  groupProps: HTMLAttributes<HTMLElement>
}

declare function useCheckboxGroup(props: CheckboxGroupProps): CheckboxGroupAria;

We may also want to support additional Spectrum-specific options like layout orientation, emphasized visual state, labeling visual options, etc.

Example:

<CheckboxGroup label="Favorite sports">
  <Checkbox value="running">Running</Checkbox>
  <Checkbox value="swimming">Swimming</Checkbox>
  <Checkbox value="soccer">Soccer</Checkbox>
</CheckboxGroup>

HTML structure:

<div role="group" aria-labelledby="label-id">
  <div id="label-id">Favorite Sports</div>
  <!-- insert checkboxes here -->
</div>

In terms of CSS, we should be able to use the Spectrum FieldGroup CSS for this (same as used in RadioGroup).

🧢 Your Company/Team

RSP

[Andarist]

I can look into this next week. I'm mostly interested in @react-aria and @react-stately parts of this though.

[devongovett]

@Andarist that would be awesome! There's no requirement to implement the Spectrum-specific parts. You could just make a basic example component using the hooks and use that in the storybook/tests for now, and we can take care of the Spectrum part later. 😄

[Andarist]

I've started working on this but I've encountered conceptual problems.

Right now useCheckbox & co are implemented on top of useToggle & co. The problem is that because of this interfaces of useRadio & useCheckbox differs quite a bit - useRadio requires RadioGroupState while useCheckbox requires ToggleState (which is intended to handle standalone toggle/checkbox).

Given the architecture of @react-aria project and how things work together, I have 2 ideas on how we could solve this:

• accept groupState in useToggle and compute returned { isSelected, setSelected } based on it, with an addition of using useControlledState differently when groupState is provided. It ain't perfect because useToggleState already handles controlled/uncontrolled scenarios based on the first argument (props)
• introduce a new hook - useGroupedCheckbox which would accept groupState and return the same interface as useToggleState, so that could be fed to useCheckbox. This would probably result in a more dedicated API and thus its implementation would be more intuitive.

I'm also unsure where should I put useCheckboxGroupState as there is no @react-stately/checkbox. Is it OK to just put it in @react-stately/toggle? Or should @react-stately/checkbox be created?

Thoughts?

[devongovett]

Good questions. Could you implement it by making the checkboxes controlled? e.g. pass isSelected={state.isSelected(value)} and an onChange handler to each checkbox in the group, where state.isSelected is a function that returns whether a given value is selected? Or you could use a context consumed in the Checkbox component that gets the group state and passes isSelected and onChange options to useToggleState maybe, as if it were controlled?