Checkbox Group

<quiet-checkbox-group>

stable

since 1.0

Checkbox groups let you attach a label and description to a group of related checkboxes or switches.

You can use checkboxes without grouping them but, when you want to apply a label and description to a group of related checkboxes, this component will come in handy.

              
                Catnip
                Food
                Litter
                Treats

<quiet-checkbox-group label="Things for the cats" description="Select as few or as many as you'd like.">
  <quiet-checkbox name="catnip">Catnip</quiet-checkbox>
  <quiet-checkbox name="food">Food</quiet-checkbox>
  <quiet-checkbox name="litter">Litter</quiet-checkbox>
  <quiet-checkbox name="treats">Treats</quiet-checkbox>
</quiet-checkbox-group>

Examples Jump to heading

Labels and descriptions Jump to heading

You can use the label and description attributes to provide plain text labels and descriptions for the checkbox group. If you want to provide HTML, use the label and description slots instead.

For more information, visit our website.

Catnip

Food

Litter

Treats

<quiet-checkbox-group label="Things for the cats">
  <span slot="description">
    For more information, <a href="https://example.com/" target="_blank">visit our website</a>.
  </span>
  <quiet-checkbox name="catnip">Catnip</quiet-checkbox>
  <quiet-checkbox name="food">Food</quiet-checkbox>
  <quiet-checkbox name="litter">Litter</quiet-checkbox>
  <quiet-checkbox name="treats">Treats</quiet-checkbox>
</quiet-checkbox-group>

Changing the orientation Jump to heading

To stack checkboxes on top of each other instead of side by side, set the orientation attribute to vertical.

              
                Behind the couch
                In the backyard
                On top of the refrigerator
                Under the bed

<quiet-checkbox-group label="Places to hide" orientation="vertical">
  <quiet-checkbox name="couch">Behind the couch</quiet-checkbox>
  <quiet-checkbox name="backyard">In the backyard</quiet-checkbox>
  <quiet-checkbox name="fridge">On top of the refrigerator</quiet-checkbox>
  <quiet-checkbox name="bed">Under the bed</quiet-checkbox>
</quiet-checkbox-group>

Grouping switches Jump to heading

You can also group switches in a checkbox group. For best results, avoid mixing checkboxes and switches in the same group.

              
                Eating
                Hiding
                Purring
                Sleeping

<quiet-checkbox-group 
  label="Remote control kitty" 
  description="Toggle an option and watch your cat react instantly!"
>
  <quiet-switch name="eating">Eating</quiet-switch>
  <quiet-switch name="hiding">Hiding</quiet-switch>
  <quiet-switch name="purring">Purring</quiet-switch>
  <quiet-switch name="sleeping">Sleeping</quiet-switch>
</quiet-checkbox-group>

Adding a required indicator Jump to heading

Use the required attribute to show a required indicator in the checkbox group's label. This just adds a visual indicator. To perform validation, use the checkbox's required and/or custom-validity attributes.

<form action="about:blank" method="get" target="_blank" id="checkbox-group__required">
  <quiet-checkbox-group 
    label="Things for the cats" 
    description="Please select at least two items."
    required 
  >
    <quiet-checkbox name="catnip" custom-validity="Select at least two items before continuing.">Catnip</quiet-checkbox>
    <quiet-checkbox name="food">Food</quiet-checkbox>
    <quiet-checkbox name="litter">Litter</quiet-checkbox>
    <quiet-checkbox name="treats">Treats</quiet-checkbox>
  </quiet-checkbox-group>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
</form>

<script>
  const form = document.getElementById('checkbox-group__required');
  const checkboxes = form.querySelectorAll('quiet-checkbox');
  const firstCheckbox = checkboxes[0];
  const validationMessage = firstCheckbox.getAttribute('custom-validity');

  // Listen for checkboxes to be checked
  form.addEventListener('quiet-input', () => {
    const numChecked = [...checkboxes].filter(checkbox => checkbox.checked).length;

    // If less than two are checked, set the custom validation message. Otherwise, remove it.
    if (numChecked < 2) {
      firstCheckbox.customValidity = validationMessage;
    } else {
      firstCheckbox.customValidity = '';
    }    
  });
</script>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-checkbox-group> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/checkbox-group/checkbox-group.js';

To manually import <quiet-checkbox-group> from npm, use the following code.

import '@quietui/quiet/dist/components/checkbox-group/checkbox-group.js';

Slots Jump to heading

Checkbox Group supports the following slots. Learn more about using slots

Name	Description
(default)	The checkboxes to place in the group.
`label`	The checkbox's label. For plain-text labels, you can use the `label` attribute instead.
`description`	The checkbox's description. For plain-text descriptions, you can use the `description` attribute instead.

Properties Jump to heading

Checkbox Group has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`label`	The checkbox's label. If you need to provide HTML in the label, use the `label` slot instead.	`string`
`description`	The checkbox's description. If you need to provide HTML in the description, use the `description` slot instead.	`string`
`orientation`	The orientation of grouped items.	`'horizontal' 'vertical'`	`'horizontal'`
`required`	Indicates at least one option in the checkbox group is required. This just adds a visual indicator. To perform validation, use the checkbox's `required` and/or `custom-validity` attributes.	`boolean`	`false`

CSS parts Jump to heading

Checkbox Group exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`label`	The element that contains the checkbox group's label.	`::part(label)`
`description`	The element that contains the checkbox group's description.	`::part(description)`
`group`	The element that wraps the grouped checkboxes.	`::part(group)`

Checkbox Group

Examples Jump to heading #

Labels and descriptions Jump to heading #

Changing the orientation Jump to heading #

Grouping switches Jump to heading #

Adding a required indicator Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

CSS parts Jump to heading #