Checkbox Group

<afp-checkbox-group>

stable

This component uses the light DOM, so its markup and styles are part of the regular document flow.

A checkbox group component to display multiple checkboxes together.

Banana

Apple

Orange

<afp-checkbox-group hidelabel>
  <afp-checkbox value="banana">Banana</afp-checkbox>
  <afp-checkbox value="apple">Apple</afp-checkbox>
  <afp-checkbox value="orange">Orange</afp-checkbox>
</afp-checkbox-group>

<afp-checkbox-group hidelabel>
  <afp-checkbox [value]="'banana'">Banana</afp-checkbox>
  <afp-checkbox [value]="'apple'">Apple</afp-checkbox>
  <afp-checkbox [value]="'orange'">Orange</afp-checkbox>
</afp-checkbox-group>

<AfpCheckboxGroup hidelabel>
  <AfpCheckbox value="banana">Banana</AfpCheckbox>
  <AfpCheckbox value="apple">Apple</AfpCheckbox>
  <AfpCheckbox value="orange">Orange</AfpCheckbox>
</AfpCheckboxGroup>

<AfpCheckboxGroup hidelabel>
  <AfpCheckbox :value="'banana'">Banana</AfpCheckbox>
  <AfpCheckbox :value="'apple'">Apple</AfpCheckbox>
  <AfpCheckbox :value="'orange'">Orange</AfpCheckbox>
</AfpCheckboxGroup>

Examples #

Label #

Use the label attribute or slot to provide a label for the checkbox group.

John Doe

Jane Doe Online

Alex Smith

<afp-checkbox-group label="Notifications for selected users">
  <afp-checkbox value="john-doe">
    <afp-avatar shape="pill" size="small" image="https://picsum.photos/100"></afp-avatar>
    John Doe
  </afp-checkbox>

  <afp-checkbox value="jane-doe">
    <afp-avatar shape="pill" size="small" image="https://picsum.photos/150"></afp-avatar>
    Jane Doe
    <afp-badge appearance="filled" variant="success">Online</afp-badge>
  </afp-checkbox>

  <afp-checkbox value="alex-smith">
    <afp-avatar shape="pill" size="small" image="https://picsum.photos/200"></afp-avatar>
    Alex Smith
  </afp-checkbox>
</afp-checkbox-group>

<afp-checkbox-group [label]="'Notifications for selected users'">
  <afp-checkbox [value]="'john-doe'">
    <afp-avatar [shape]="'pill'" [size]="'small'" [image]="'https://picsum.photos/100'"></afp-avatar>
    John Doe
  </afp-checkbox>

  <afp-checkbox [value]="'jane-doe'">
    <afp-avatar [shape]="'pill'" [size]="'small'" [image]="'https://picsum.photos/150'"></afp-avatar>
    Jane Doe
    <afp-badge [appearance]="'filled'" [variant]="'success'">Online</afp-badge>
  </afp-checkbox>

  <afp-checkbox [value]="'alex-smith'">
    <afp-avatar [shape]="'pill'" [size]="'small'" [image]="'https://picsum.photos/200'"></afp-avatar>
    Alex Smith
  </afp-checkbox>
</afp-checkbox-group>

<AfpCheckboxGroup label="Notifications for selected users">
  <AfpCheckbox value="john-doe">
    <AfpAvatar shape="pill" size="small" image="https://picsum.photos/100"></AfpAvatar>
    John Doe
  </AfpCheckbox>

  <AfpCheckbox value="jane-doe">
    <AfpAvatar shape="pill" size="small" image="https://picsum.photos/150"></AfpAvatar>
    Jane Doe
    <AfpBadge appearance="filled" variant="success">Online</AfpBadge>
  </AfpCheckbox>

  <AfpCheckbox value="alex-smith">
    <AfpAvatar shape="pill" size="small" image="https://picsum.photos/200"></AfpAvatar>
    Alex Smith
  </AfpCheckbox>
</AfpCheckboxGroup>

<AfpCheckboxGroup :label="'Notifications for selected users'">
  <AfpCheckbox :value="'john-doe'">
    <AfpAvatar :shape="'pill'" :size="'small'" :image="'https://picsum.photos/100'"></AfpAvatar>
    John Doe
  </AfpCheckbox>

  <AfpCheckbox :value="'jane-doe'">
    <AfpAvatar :shape="'pill'" :size="'small'" :image="'https://picsum.photos/150'"></AfpAvatar>
    Jane Doe
    <AfpBadge :appearance="'filled'" :variant="'success'">Online</AfpBadge>
  </AfpCheckbox>

  <AfpCheckbox :value="'alex-smith'">
    <AfpAvatar :shape="'pill'" :size="'small'" :image="'https://picsum.photos/200'"></AfpAvatar>
    Alex Smith
  </AfpCheckbox>
</AfpCheckboxGroup>

Hint #

Use the hint attribute to provide additional information below the checkbox group.

Red

Blue

Green

<afp-checkbox-group 
  label="Choose preferred colors"
  hint="Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua"
>
  <afp-checkbox value="red">Red</afp-checkbox>
  <afp-checkbox value="blue" disabled>Blue</afp-checkbox>
  <afp-checkbox value="green">Green</afp-checkbox>
</afp-checkbox-group>

<afp-checkbox-group 
  [label]="'Choose preferred colors'"
  [hint]="'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua'"
>
  <afp-checkbox [value]="'red'">Red</afp-checkbox>
  <afp-checkbox [value]="'blue'" disabled>Blue</afp-checkbox>
  <afp-checkbox [value]="'green'">Green</afp-checkbox>
</afp-checkbox-group>

<AfpCheckboxGroup 
  label="Choose preferred colors"
  hint="Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua"
>
  <AfpCheckbox value="red">Red</AfpCheckbox>
  <AfpCheckbox value="blue" disabled>Blue</AfpCheckbox>
  <AfpCheckbox value="green">Green</AfpCheckbox>
</AfpCheckboxGroup>

<AfpCheckboxGroup 
  :label="'Choose preferred colors'"
  :hint="'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua'"
>
  <AfpCheckbox :value="'red'">Red</AfpCheckbox>
  <AfpCheckbox :value="'blue'" disabled>Blue</AfpCheckbox>
  <AfpCheckbox :value="'green'">Green</AfpCheckbox>
</AfpCheckboxGroup>

Value #

Use the value attribute to set the initial selected checkboxes.

Rock

Jazz

Pop

<afp-checkbox-group label="Favorite music genres" value='["jazz","pop"]'>
  <afp-checkbox value="rock">Rock</afp-checkbox>
  <afp-checkbox value="jazz">Jazz</afp-checkbox>
  <afp-checkbox value="pop">Pop</afp-checkbox>
</afp-checkbox-group>

<afp-checkbox-group [label]="'Favorite music genres'" value='["jazz","pop"]'>
  <afp-checkbox [value]="'rock'">Rock</afp-checkbox>
  <afp-checkbox [value]="'jazz'">Jazz</afp-checkbox>
  <afp-checkbox [value]="'pop'">Pop</afp-checkbox>
</afp-checkbox-group>

<AfpCheckboxGroup label="Favorite music genres" value='["jazz","pop"]'>
  <AfpCheckbox value="rock">Rock</AfpCheckbox>
  <AfpCheckbox value="jazz">Jazz</AfpCheckbox>
  <AfpCheckbox value="pop">Pop</AfpCheckbox>
</AfpCheckboxGroup>

<AfpCheckboxGroup :label="'Favorite music genres'" value='["jazz","pop"]'>
  <AfpCheckbox :value="'rock'">Rock</AfpCheckbox>
  <AfpCheckbox :value="'jazz'">Jazz</AfpCheckbox>
  <AfpCheckbox :value="'pop'">Pop</AfpCheckbox>
</AfpCheckboxGroup>

Disabled #

Use the disabled attribute to render the entire checkbox group in the disabled state.

Technology

Science

Design

<afp-checkbox-group label="Topics of interest" disabled>
  <afp-checkbox value="technology">Technology</afp-checkbox>
  <afp-checkbox value="science">Science</afp-checkbox>
  <afp-checkbox value="design">Design</afp-checkbox>
</afp-checkbox-group>

<afp-checkbox-group [label]="'Topics of interest'" disabled>
  <afp-checkbox [value]="'technology'">Technology</afp-checkbox>
  <afp-checkbox [value]="'science'">Science</afp-checkbox>
  <afp-checkbox [value]="'design'">Design</afp-checkbox>
</afp-checkbox-group>

<AfpCheckboxGroup label="Topics of interest" disabled>
  <AfpCheckbox value="technology">Technology</AfpCheckbox>
  <AfpCheckbox value="science">Science</AfpCheckbox>
  <AfpCheckbox value="design">Design</AfpCheckbox>
</AfpCheckboxGroup>

<AfpCheckboxGroup :label="'Topics of interest'" disabled>
  <AfpCheckbox :value="'technology'">Technology</AfpCheckbox>
  <AfpCheckbox :value="'science'">Science</AfpCheckbox>
  <AfpCheckbox :value="'design'">Design</AfpCheckbox>
</AfpCheckboxGroup>

Invalid #

Use the invalid attribute to render a checkbox in the invalid state with an error message.

SMS

Push Notifications

<afp-checkbox-group label="Notification types" invalid="Please select at least one option">
  <afp-checkbox value="email">Email</afp-checkbox>
  <afp-checkbox value="sms">SMS</afp-checkbox>
  <afp-checkbox value="push">Push Notifications</afp-checkbox>
</afp-checkbox-group>

<afp-checkbox-group [label]="'Notification types'" [invalid]="'Please select at least one option'">
  <afp-checkbox [value]="'email'">Email</afp-checkbox>
  <afp-checkbox [value]="'sms'">SMS</afp-checkbox>
  <afp-checkbox [value]="'push'">Push Notifications</afp-checkbox>
</afp-checkbox-group>

<AfpCheckboxGroup label="Notification types" invalid="Please select at least one option">
  <AfpCheckbox value="email">Email</AfpCheckbox>
  <AfpCheckbox value="sms">SMS</AfpCheckbox>
  <AfpCheckbox value="push">Push Notifications</AfpCheckbox>
</AfpCheckboxGroup>

<AfpCheckboxGroup :label="'Notification types'" :invalid="'Please select at least one option'">
  <AfpCheckbox :value="'email'">Email</AfpCheckbox>
  <AfpCheckbox :value="'sms'">SMS</AfpCheckbox>
  <AfpCheckbox :value="'push'">Push Notifications</AfpCheckbox>
</AfpCheckboxGroup>

Event Handling #

Use the afp-value-changed event to listen for value changes.

Weather

Tasks

News

<afp-checkbox-group id="demo-checkbox-group" hint="Event output: []" label="Show dashboard widgets">
  <afp-checkbox value="weather">Weather</afp-checkbox>
  <afp-checkbox value="tasks">Tasks</afp-checkbox>
  <afp-checkbox value="news">News</afp-checkbox>
</afp-checkbox-group>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const checkboxGroupEl = document.querySelector('#demo-checkbox-group');

    checkboxGroupEl.addEventListener('afp-value-changed', (event) => {
      checkboxGroupEl.hint = `Event output: ${JSON.stringify(event.detail)}`;
    });
  });
</script>

<afp-checkbox-group [id]="'demo-checkbox-group'" [hint]="'Event output: []'" [label]="'Show dashboard widgets'">
  <afp-checkbox [value]="'weather'">Weather</afp-checkbox>
  <afp-checkbox [value]="'tasks'">Tasks</afp-checkbox>
  <afp-checkbox [value]="'news'">News</afp-checkbox>
</afp-checkbox-group>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const checkboxGroupEl = document.querySelector('#demo-checkbox-group');

    checkboxGroupEl.addEventListener('afp-value-changed', (event) => {
      checkboxGroupEl.hint = `Event output: ${JSON.stringify(event.detail)}`;
    });
  });
</script>

<AfpCheckboxGroup id="demo-checkbox-group" hint="Event output: []" label="Show dashboard widgets">
  <AfpCheckbox value="weather">Weather</AfpCheckbox>
  <AfpCheckbox value="tasks">Tasks</AfpCheckbox>
  <AfpCheckbox value="news">News</AfpCheckbox>
</AfpCheckboxGroup>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const checkboxGroupEl = document.querySelector('#demo-checkbox-group');

    checkboxGroupEl.addEventListener('afp-value-changed', (event) => {
      checkboxGroupEl.hint = `Event output: ${JSON.stringify(event.detail)}`;
    });
  });
</script>

<AfpCheckboxGroup :id="'demo-checkbox-group'" :hint="'Event output: []'" :label="'Show dashboard widgets'">
  <AfpCheckbox :value="'weather'">Weather</AfpCheckbox>
  <AfpCheckbox :value="'tasks'">Tasks</AfpCheckbox>
  <AfpCheckbox :value="'news'">News</AfpCheckbox>
</AfpCheckboxGroup>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const checkboxGroupEl = document.querySelector('#demo-checkbox-group');

    checkboxGroupEl.addEventListener('afp-value-changed', (event) => {
      checkboxGroupEl.hint = `Event output: ${JSON.stringify(event.detail)}`;
    });
  });
</script>

Properties

Learn more about properties.

Name Description Reflects

value

value of the checkbox group

Type string[]

label

Group label

Type string

hideLabel
hidelabel

hides the label visually

Type boolean

hint

hint footer property of checkbox group

Type string

invalid

Error message shown below the checkbox when present. Sets `aria-invalid`. Provide a non-empty string to put the component in an error state.

Type string

disabled

Disable all checkboxes in the group (unless the child has explicit disabled attribute)

Type boolean

Default false

shape

shape of the checkbox group

Type

AfpShape

Name	Description
`PILL`	Makes the component circular.
`ROUNDED`	Makes the component rounded.
`SOFT`	Makes the component have soft edges.
`SQUARE`	Makes the component square.

AfpShape

Default AfpShape.ROUNDED

size

size of the checkboxes.

Type

AfpSize

Name	Description
`SMALL`	Small size with compact dimensions.
`MEDIUM`	Medium size with standard dimensions.
`LARGE`	Large size with expanded dimensions.

AfpSize

Default AfpSize.MEDIUM

componentId

Unique component ID

Default `afp-checkbox-group-${++id}`

Events

Learn more about events.

Name	Return	Description
`afp-value-changed`	`string[]`	Emitted when the value of the checkbox group changes.

Slots

Learn more about slots.

Name	Description
`default`	The default slot.
`label`	Slot for the checkbox group label.

Internationalization

Learn more about internationalization.

Key	Description
`checkbox-group.aria-label`	The default `aria-label` text for Checkbox Group

CSS Parts

Learn more about CSS Parts.

Name	Description	Selector
`base`	The checkbox group container wrapper.	`::part(base)`
`label`	The checkbox group label.	`::part(label)`
`items`	The container for the checkbox items.	`::part(items)`
`invalid`	The error message container.	`::part(invalid)`
`hint`	The hint text container.	`::part(hint)`

CSS Custom Properties

Name	Description	Default
`--afp-input-error-message-color`	The color of the error message in the invalid/error state.	`--afp-color-error-500`

Dependencies

The component automatically brings in the listed items, including any nested dependencies that may exist.

afp-checkbox

Importing

Using the bundle is the recommended method to include components. If you’d rather handle imports manually, you can use the code examples below.

import '@afp-design-system/core/dist/components/checkbox-group/checkbox-group.js';