Checkbox Group

<wa-checkbox-group>

Stable

modified

Checkbox groups wrap related checkboxes so they keep Web Awesome's labeling semantics while also behaving as a single aggregate form control with a shared array value.

Checkboxes in a group remain independent form controls with their own name, value, and validation. The group exists to provide a shared label, hint, and accessible grouping.

  Design
  Development
  Marketing

<wa-checkbox-group label="Interests" name="interests">
  <wa-checkbox value="design">Design</wa-checkbox>
  <wa-checkbox value="development">Development</wa-checkbox>
  <wa-checkbox value="marketing">Marketing</wa-checkbox>
</wa-checkbox-group>

Examples

Link to This Section

Label

Link to This Section

Use the label attribute to give the group an accessible label. For labels that contain HTML, use the label slot instead.

  Pepperoni
  Mushrooms
  Onions
  Peppers
  Sausage
  Extra cheese


                  
                

<wa-checkbox-group label="Toppings" name="toppings">
  <wa-checkbox value="pepperoni">Pepperoni</wa-checkbox>
  <wa-checkbox value="mushrooms">Mushrooms</wa-checkbox>
  <wa-checkbox value="onions">Onions</wa-checkbox>
  <wa-checkbox value="peppers">Peppers</wa-checkbox>
  <wa-checkbox value="sausage">Sausage</wa-checkbox>
  <wa-checkbox value="extra-cheese">Extra cheese</wa-checkbox>
</wa-checkbox-group>

Hint

Link to This Section

Add a descriptive hint to a checkbox group with the hint attribute. For hints that contain HTML, use the hint slot instead.

  Monday
  Wednesday
  Friday

<wa-checkbox-group label="Workdays" hint="Choose as many as you like." name="workdays">
  <wa-checkbox value="monday">Monday</wa-checkbox>
  <wa-checkbox value="wednesday">Wednesday</wa-checkbox>
  <wa-checkbox value="friday">Friday</wa-checkbox>
</wa-checkbox-group>

Orientation

Link to This Section

Checkbox groups stack vertically by default. Set the orientation attribute to horizontal to lay them out in a row.

  Small
  Medium
  Large

<wa-checkbox-group label="Sizes" orientation="horizontal" name="sizes">
  <wa-checkbox value="small">Small</wa-checkbox>
  <wa-checkbox value="medium">Medium</wa-checkbox>
  <wa-checkbox value="large">Large</wa-checkbox>
</wa-checkbox-group>

Size

Link to This Section

The size of grouped checkboxes and switches is determined by the checkbox group's size attribute. Any size set on individual items will be overridden.

  
    Option 1
    Option 2
  
    Option 1
    Option 2
  
    Option 1
    Option 2
  
    Option 1
    Option 2
  
    Option 1
    Option 2

<div class="wa-stack">
  <wa-checkbox-group label="Extra small" size="xs" name="xs">
    <wa-checkbox value="option-1">Option 1</wa-checkbox>
    <wa-checkbox value="option-2">Option 2</wa-checkbox>
  </wa-checkbox-group>
  <wa-checkbox-group label="Small" size="s" name="s">
    <wa-checkbox value="option-1">Option 1</wa-checkbox>
    <wa-checkbox value="option-2">Option 2</wa-checkbox>
  </wa-checkbox-group>
  <wa-checkbox-group label="Medium" size="m" name="m">
    <wa-checkbox value="option-1">Option 1</wa-checkbox>
    <wa-checkbox value="option-2">Option 2</wa-checkbox>
  </wa-checkbox-group>
  <wa-checkbox-group label="Large" size="l" name="l">
    <wa-checkbox value="option-1">Option 1</wa-checkbox>
    <wa-checkbox value="option-2">Option 2</wa-checkbox>
  </wa-checkbox-group>
  <wa-checkbox-group label="Extra large" size="xl" name="xl">
    <wa-checkbox value="option-1">Option 1</wa-checkbox>
    <wa-checkbox value="option-2">Option 2</wa-checkbox>
  </wa-checkbox-group>
</div>

Disabled

Link to This Section

A checkbox group itself can't be disabled. Add the disabled attribute to individual checkboxes to disable them.

  Insurance
  Gift wrap
  Express shipping
  Extended warranty

<wa-checkbox-group label="Add-ons" name="addons">
  <wa-checkbox value="insurance" disabled>Insurance</wa-checkbox>
  <wa-checkbox value="gift-wrap" disabled>Gift wrap</wa-checkbox>
  <wa-checkbox value="express-shipping">Express shipping</wa-checkbox>
  <wa-checkbox value="extended-warranty">Extended warranty</wa-checkbox>
</wa-checkbox-group>

Switches

Link to This Section

A checkbox group also works with switches.

  Email
  SMS
  Push

<wa-checkbox-group label="Notifications" hint="Pick at least one channel." name="notifications">
  <wa-switch value="email">Email</wa-switch>
  <wa-switch value="sms">SMS</wa-switch>
  <wa-switch value="push">Push</wa-switch>
</wa-checkbox-group>

Required

Link to This Section

The required attribute adds a visual indicator to the group's label. Because each checkbox is an independent control, the checkbox group doesn't enforce the requirement. Set the required property on the checkbox or call its setCustomValidity() method to control validation.

  
    I agree to the terms and conditions
  
  Submit

<form>
  <wa-checkbox-group label="Accept terms" required name="accept">
    <wa-checkbox value="terms" required>I agree to the terms and conditions</wa-checkbox>
  </wa-checkbox-group>
  <br />
  <wa-button type="submit" appearance="filled">Submit</wa-button>
</form>

Yoummday Extensions

Link to This Section

The Yoummday checkbox group keeps Web Awesome's labeling and layout semantics, but it also behaves as a single form control with an aggregated value array. This matches the legacy Yoummday behavior that treated a group of checkboxes as one required field and one submission value source.

Aggregate Value And Form Submission

Link to This Section

When you set name on the group, every selected child value is submitted under that one field name.

  
    Contracts
    Payments
    Compliance
  
  Submit

<form class="wa-stack" onsubmit="event.preventDefault(); alert(JSON.stringify([...new FormData(event.target)]))">
  <wa-checkbox-group label="Topics" name="topics" hint="Pick as many as apply" required>
    <wa-checkbox value="contracts">Contracts</wa-checkbox>
    <wa-checkbox value="payments">Payments</wa-checkbox>
    <wa-checkbox value="compliance">Compliance</wa-checkbox>
  </wa-checkbox-group>

  <wa-button type="submit" variant="brand">Submit</wa-button>
</form>

Migrated Naming

Link to This Section

Legacy alignment becomes orientation, and help-text becomes hint. Group-level sl-input and sl-change become native input and change.

API

Link to This Section

Importing

Link to This Section

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

CDN

npm

Self-Hosted

React

Import this component directly from the CDN:

import 'https://cdn.yoummday.com/packages/@yoummday/webawesome/0.5.1/dist/components/checkbox-group/checkbox-group.js';

After installing Web Awesome via npm, import this component:

import '@yoummday/webawesome/dist/components/checkbox-group/checkbox-group.js';

If you're self-hosting Web Awesome, import this component from your server:

import './webawesome/dist/components/checkbox-group/checkbox-group.js';

To import this component for React 18 or below, use the following code:

import YoummdayCheckboxGroup from '@yoummday/webawesome/dist/react/checkbox-group/index.js';

Slots

Link to This Section

Learn more about using slots.

Name	Description
(default)	The default slot where `<wa-checkbox>` or `<wa-switch>` elements are placed.
`hint`	Text that describes how to use the checkbox group. Alternatively, you can use the `hint` attribute.
`label`	The checkbox group's label. Required for proper accessibility. Alternatively, you can use the `label` attribute.

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Name	Description	Reflects
`defaultValue`	The default value used when resetting a parent form. Type `string[]` Default `[]`
`disabled` `disabled`	Disables the group and all child toggles. Type `boolean` Default `false`
`hint` `hint`	The checkbox group's hint. If you need to display HTML, use the `hint` slot instead. Type `string` Default `''`
`label` `label`	The checkbox group's label. Required for proper accessibility. If you need to display HTML, use the `label` slot instead. Type `string` Default `''`
`name` `name`	The name of the group, submitted for each selected value. Type `string \| null` Default `null`
`orientation` `orientation`	The orientation in which to show grouped checkboxes. Type `'horizontal' \| 'vertical'` Default `'vertical'`
`required` `required`	Indicates that at least one option should be selected. This only adds a visual indicator to the label. To enforce the requirement, use the `required` attribute on the individual checkboxes and/or their `setCustomValidity()` method. Type `boolean` Default `false`
`size` `size`	The group's size. When present, this size will be applied to all `<wa-checkbox>` and `<wa-switch>` items inside. Type `'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| 'small' \| 'medium' \| 'large'`
`value`	The group's current selected values. Type `string[]` Default `[]`
`withHint` `with-hint`	Only required for SSR. Set to `true` if you're slotting in a `hint` element so the server-rendered markup includes the hint before the component hydrates on the client. Type `boolean` Default `false`
`withLabel` `with-label`	Only required for SSR. Set to `true` if you're slotting in a `label` element so the server-rendered markup includes the label before the component hydrates on the client. Type `boolean` Default `false`

Events

Link to This Section

Learn more about events.

Name	Description
`change`	Emitted when the group's aggregated value changes due to user interaction.
`input`	Emitted when the group's aggregated value changes due to user interaction.
`wa-invalid`	Emitted when the group fails constraint validation.

CSS Custom Properties

Link to This Section

Learn more about CSS custom properties.

Name	Description
`--gap`	The gap between grouped checkboxes. Default `0.5em`

CSS Parts

Link to This Section

Learn more about CSS parts.

Name	Description	CSS selector
`form-control`	The form control that wraps the label, group, and hint.	`::part(form-control)`
`form-control-input`	The element that wraps the grouped checkboxes and switches.	`::part(form-control-input)`
`form-control-label`	The label's wrapper.	`::part(form-control-label)`
`hint`	The hint's wrapper.	`::part(hint)`
`items`	Alias of `form-control-input`, retained for migrated consumers.	`::part(items)`

Dependencies

Link to This Section

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

Need a hand?

Report a bug

Ask for help

Checkbox Group

Examples

Label

Hint

Orientation

Size

Disabled

Switches

Required

Yoummday Extensions

Aggregate Value And Form Submission

Migrated Naming

API

Importing

Slots

Attributes & Properties

Events

CSS Custom Properties

CSS Parts

Dependencies

Quick Links

Recent Searches