Checkbox Group

<wa-checkbox-group>

Stable

Checkbox groups wrap a set of related checkboxes or switches so they share a label, hint, and grouping semantics.

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">
  <wa-checkbox name="design">Design</wa-checkbox>
  <wa-checkbox name="development">Development</wa-checkbox>
  <wa-checkbox name="marketing">Marketing</wa-checkbox>
</wa-checkbox-group>

Examples

Link to This Section

Labels

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">
  <wa-checkbox name="pepperoni">Pepperoni</wa-checkbox>
  <wa-checkbox name="mushrooms">Mushrooms</wa-checkbox>
  <wa-checkbox name="onions">Onions</wa-checkbox>
  <wa-checkbox name="peppers">Peppers</wa-checkbox>
  <wa-checkbox name="sausage">Sausage</wa-checkbox>
  <wa-checkbox name="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.">
  <wa-checkbox name="monday">Monday</wa-checkbox>
  <wa-checkbox name="wednesday">Wednesday</wa-checkbox>
  <wa-checkbox name="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">
  <wa-checkbox name="small">Small</wa-checkbox>
  <wa-checkbox name="medium">Medium</wa-checkbox>
  <wa-checkbox name="large">Large</wa-checkbox>
</wa-checkbox-group>

Sizes

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 3
  
    Extra small
    Small
    Medium
    Large
    Extra large

<div>
  <wa-checkbox-group id="checkbox-group-size" label="Options" hint="Use the select below to change the size." size="m">
    <wa-checkbox>Option 1</wa-checkbox>
    <wa-checkbox>Option 2</wa-checkbox>
    <wa-checkbox>Option 3</wa-checkbox>
  </wa-checkbox-group>

  <wa-divider></wa-divider>

  <wa-select label="Size" value="m" style="max-width: 200px;">
    <wa-option value="xs">Extra small</wa-option>
    <wa-option value="s">Small</wa-option>
    <wa-option value="m">Medium</wa-option>
    <wa-option value="l">Large</wa-option>
    <wa-option value="xl">Extra large</wa-option>
  </wa-select>
</div>

<script>
  const checkboxGroup = document.getElementById('checkbox-group-size');
  const sizeSelect = checkboxGroup.parentElement.querySelector('wa-select');

  sizeSelect.addEventListener('change', () => (checkboxGroup.size = sizeSelect.value));
</script>

Disabling

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">
  <wa-checkbox name="insurance" disabled>Insurance</wa-checkbox>
  <wa-checkbox name="gift-wrap" disabled>Gift wrap</wa-checkbox>
  <wa-checkbox name="express-shipping">Express shipping</wa-checkbox>
  <wa-checkbox name="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.">
  <wa-switch name="email">Email</wa-switch>
  <wa-switch name="sms">SMS</wa-switch>
  <wa-switch name="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>
    <wa-checkbox name="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>

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://ka-f.webawesome.com/webawesome@0.17.0/components/checkbox-group/checkbox-group.js';

After installing Web Awesome via npm, import this component:

import '@awesome.me/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 WaCheckboxGroup from '@awesome.me/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
`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 `''`
`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'`
`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`

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, exposed as a `role="group"`.	`::part(form-control-input)`
`form-control-label`	The label's wrapper.	`::part(form-control-label)`
`hint`	The hint's wrapper.	`::part(hint)`

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

Labels

Hint

Orientation

Sizes

Disabling

Switches

Required

Importing

Slots

Attributes & Properties

CSS Custom Properties

CSS Parts

Dependencies

Quick Links

Recent Searches