Aqua Basis

The AqCheckboxGroup component is a container element used to manage and render a collection of checkboxes. It provides a consistent structure for grouping related options, handling selection states, and improving accessibility.

By using AqCheckboxGroup, you can easily configure multiple checkboxes through the options prop, which maps directly to the props of individual checkbox variant components. This approach ensures cleaner code, better form integration, and a predictable API across frameworks.

<aq-checkbox-group
  orientation="vertical"
  type="checkbox"
  label="This is a checkbox"
  info="This is an information tooltip"
  is-required
  helper-text="This is a helper text"
></aq-checkbox-group>

Props and Attributes

Prop / Attr	Type	Default	Description
`label`	`string`	`''`	Main label text displayed next to the checkbox.
`info`	`string`	`''`	Tooltip text.
`isRequired`	`boolean`	`false`	Displays an asterisk (*) indicating that the field is required.
`isDisabled`	`boolean`	`false`	Disables interaction with the checkbox.
`helperText`	`boolean`	`''`	Provides additional guidance or context for the checkbox group.

Use horizontal to display them side by side, or vertical to stack them in a column. |

PlayGround

You can interact with the component and experiment with its attributes and properties directly in this playground.

In the Code tab, the generated code snippet is available.

In addition to the interactive examples in this documentation, you can explore the full playground with all supported options and advanced configurations at the following link:

👉 Open full playground

https://aqua-ds-playground.masivianlabs.com/doc-storybook/index.html?path=/story/components-forms-aqcheckboxgroup--default&nav=0

<aside> ⚠️

Important: The code shown is in Web Component format. If you are using a specific framework (Vue, React, Angular), you must adapt it to the framework’s conventions before using it.

</aside>

Events

Event	Description	React	Angular	Vue	Web Components
`change`	Triggered when the checkbox group state changes. Typically when selecting a checkbox.	`onChange={handleChange}`	`(change)="handleChange($event)"`	`@change="handleChange"`	`addEventListener('change', handler)`
`input`	Triggered when the checkbox group state changes. Typically when selecting a checkbox.	`onInput={handleInput}`	`(input)="handleInput($event)"`	`@input="handleInput"`	`addEventListener('input', handler)`

Event Types

Event	React	Angular	Vue
`change`	`(e:React.ChangeEvent<HTMLAqCheckboxGroupElement>)`	`(e:Event)`	`(e:CustomEvent)`

Variants

To use each of the Checkbox Variants (AqCheckbox, AqCheckboxButton and AqCheckboxCard) ****inside a Checkbox Group, you must provide the options prop as an array of objects. Each object represents a single Checkbox and its properties should match the props of the standalone Checkbox Variant component.

// Example checkbox group options using the checkbox-card variant
const checkboxGroupOptions = [
  {
	  label: "Ross",
	  isChecked: true,
	  valueCheckbox: "option-1",
	  subLabel: "This is a sublabel ",
	  isDisabled: true,
	  icon: "aq-icon-message"
	},
	{
	  label: "Rachel",
	  valueCheckbox: "option-2",
	  icon: "aq-icon-message",
	  subLabel: "This is a sublabel ",
	  tooltipWidth: "100px"
	},
	{
	  valueCheckbox: "option-3",
	  label: "Chandler",
	  subLabel: "This is a long sublabel to test multiline"
	}
]

AqCheckboxButton

See AqCheckboxButton to know the list of props and proper usage.

Example options inside AqCheckboxGroup

// Example checkbox group options using the checkbox-button variant
const checkboxGroupButtonOptions = [
  {
	  label: "Ross",
	  icon: "aq-icon-message",
	  info: "This is short tooltip",
	  isChecked: true,
	  valueCheckbox: "option-1",
	  idCheckbox: "option-1duao",
	  name: "checkbox-button-1",	  
	  isDisabled: true,
	},
	{
	  label: "Rachel",
	  icon: "aq-icon-message",
	  info: "This is short tooltip",
	  valueCheckbox: "option-1",
	  idCheckbox: "option-2yuap",
	  name: "checkbox-button-2"
	},
	{
	  valueCheckbox: "option-3",
	  label: "Chandler",
	}
]

Events

All events are emitted by the AqCheckboxGroup.

AqCheckboxCard

See AqCheckboxCard to know the list of props and proper usage.

Example options inside AqCheckboxGroup

// Example checkbox group options using the checkbox-card variant
const checkboxGroupButtonOptions = [
  {
	  label: "Ross",
	  isChecked: true,
	  valueCheckbox: "option-1",
	  subLabel: "This is a sublabel ",
	  isDisabled: true,
	  icon: "aq-icon-message"
	},
	{
	  label: "Rachel",
	  valueCheckbox: "option-2",
	  icon: "aq-icon-message",
	  subLabel: "This is a sublabel ",
	  tooltipWidth: "100px"
	},
	{
	  valueCheckbox: "option-3",
	  label: "Chandler",
	  subLabel: "This is a long sublabel to test multiline"
	}
]

Events

All events are emitted by the AqCheckboxGroup.

Binding Support by Framework

AqCheckboxGroup works seamlessly with the two-way binding mechanisms provided by frameworks. This allows the group to stay in sync with your application state, making it easier to manage selected values and integrate with forms while keeping the API consistent across different frameworks.

| --- | --- | --- | --- |

In Frameworks

Web Components

<aq-checkbox-group
  id="aq-checkbox-group-card"
  orientation="vertical"
  type="checkbox-card"
  label="This is a checkbox"
  info="This is an information tooltip"
  is-required
  helper-text="This is a helper text"
>
</aq-checkbox-group>

<script>
  const checkboxGroupCard = document.getElementById('aq-checkbox-group-card');
  const infoCheckboxGroup = [
    {
      label: "Ross",
      isChecked: true,
      valueCheckbox: "option-1",
      subLabel: "This is a sublabel ",
      isDisabled: true,
      icon: "aq-icon-message"
    },
    {
      label: "Rachel",
      valueCheckbox: "option-2",
      icon: "aq-icon-message",
      subLabel: "This is a sublabel ",
      tooltipWidth: "100px"
    },
    {
      valueCheckbox: "option-3",
      label: "Chandler",
      subLabel: "This is a long sublabel to test multiline"
    }
  ];

  checkboxGroupCard.options = infoCheckboxGroup;

  checkboxGroupCard.addEventListener('change', (event) => {
    console.log('Change event: ', event);
  });
  checkboxGroupCard.addEventListener('input', (event) => {
    console.log('Input event: ', event);
  });
</script>

Vue

<script lang="ts">
import { AqCheckboxGroup } from '@aqua-ds/vue';
import { ref, defineComponent } from 'vue';

export default defineComponent({
  components: { AqCheckboxGroup },
  setup() {
    const selectedValueGroup = ref([]);
    const infoCheckboxGroup = ref([
      {
        label: "Ross",
        isChecked: true,
        valueCheckbox: "option-1",
        subLabel: "This is a sublabel ",
        isDisabled: true,
        icon: "aq-icon-message"
      },
      {
        label: "Rachel",
        valueCheckbox: "option-2",
        icon: "aq-icon-message",
        subLabel: "This is a sublabel ",
        tooltipWidth: "100px"
      },
      {
        valueCheckbox: "option-3",
        label: "Chandler",
        subLabel: "This is a long sublabel to test multiline"
      }
    ]);

    const handleValueChange = (ev: any) => {
      console.log('Handling checkbox custom change from vue ', ev);
    };
    const handleValueInput = (ev: any) => {
      console.log('Handling checkbox custom input from vue ', ev);
    };

    return {
      handleValueChange,
      handleValueInput,
      selectedValueGroup,
      infoCheckboxGroup,
    };
  },
});
</script>

<template>
  <div>
    <aq-checkbox-group label="This is a checkbox 4" is-required  type="checkbox-card" info="This is an information tooltip" :options="infoCheckboxGroup"
      @change="handleValueChange" @input="handleValueInput" v-model="selectedValueGroup"></aq-checkbox-group>
    <div>
      <span>Selected Value: {{ selectedValueGroup }}</span>
    </div>
  </div>
</template>

React

import { AqCheckboxGroup } from '@aqua-ds/react';
import { useState, SyntheticEvent } from 'react';

export const CheckboxGroupSet = () => {
  const [selectedValueGroup, setSelectedValueGroup] = useState<any[]>([]);

  const infoCheckboxGroup = [
    {
      label: "Ross",
      isChecked: true,
      valueCheckbox: "option-1",
      subLabel: "This is a sublabel ",
      isDisabled: true,
      icon: "aq-icon-message",
    },
    {
      label: "Rachel",
      valueCheckbox: "option-2",
      icon: "aq-icon-message",
      subLabel: "This is a sublabel ",
      tooltipWidth: "100px",
    },
    {
      valueCheckbox: "option-3",
      label: "Chandler",
      subLabel: "This is a long sublabel to test multiline",
    },
  ];

  const handleValueChange = (event: SyntheticEvent) => {
    console.log("Handling checkbox custom change from react ", event);
    const detail = (event.nativeEvent as CustomEvent).detail;
    console.log("detail", detail.value);
  };

  const handleValueInput = (event: SyntheticEvent) => {
    console.log("Handling checkbox custom input from react ", event);
    const detail = (event.nativeEvent as CustomEvent).detail;
    console.log("detail", detail);
    setSelectedValueGroup(detail.value);
  };

  return (
    <div>
      <AqCheckboxGroup
        label="This is a checkbox 4"
        isRequired
        type="checkbox-card"
        info="This is an information tooltip"
        options={infoCheckboxGroup}
        onChange={handleValueChange}
        onInput={handleValueInput}
        ></AqCheckboxGroup>

      <div>
        <span>Selected Value: {JSON.stringify(selectedValueGroup)}</span>
      </div>
    </div>
  );
};

Angular

// checkbox-set.component.ts
import { Component } from '@angular/core';
import { AqCheckbox, AWCValueAccessor } from '@aqua-ds/angular';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';

@Component({
  selector: 'app-checkbox-set',
  imports: [AqCheckbox, AWCValueAccessor, FormsModule],
  templateUrl: './checkbox-set.component.html',
})

export class CheckboxComponentSet {
	modelCheckbox = false;
	
	handleValueChanged(event: any) {
	  console.log('Value Changed:', event);
	}
}

<!-- checkbox-set.component.html -->
<aq-checkbox
	id-checkbox="checkbox-1"
	name="checkbox-1"
	label="This is a checkbox 1"
	icon="aq-icon-message"
	required
	info="This is an information tooltip"
	value-checkbox="option3"
	(input)="handleValueChanged($event)"
	[(ngModel)]="modelCheckbox">
</aq-checkbox>
<div>
	<span>Selected Value: {{ modelCheckbox }}</span>
</div>

The AqCheckbox component is fully compatible with Angular’s [(ngModel)] two-way binding. Support is enabled via native Angular forms and the AWCValueAccessor utility from @aqua-ds/angular.