Light Dark System

Checkbox Group

<zn-checkbox-group> | ZnCheckboxGroup
Since 1.0 experimental

Shotrt summary of the component’s intended use.

Examples

Basic Checkbox Group

A basic checkbox group lays out multiple checkbox items vertically.

Initiate outbound transfers Approve outbound transfers Export transactions 
<zn-checkbox-group label="Financial products permissions" name="a">
  <zn-checkbox value="initiate-outbound">Initiate outbound transfers</zn-checkbox>
  <zn-checkbox value="approve-outbound">Approve outbound transfers </zn-checkbox>
  <zn-checkbox value="export">Export transactions</zn-checkbox>
</zn-checkbox-group>

Help Text

Add descriptive help text to a checkbox group with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

Initiate outbound transfers Approve outbound transfers Export transactions 
<zn-checkbox-group label="Financial products permissions" help-text="Outbound transfers require separate initiators and approvers" name="a">
  <zn-checkbox value="initiate-outbound">Initiate outbound transfers</zn-checkbox>
  <zn-checkbox value="approve-outbound">Approve outbound transfers </zn-checkbox>
  <zn-checkbox value="export">Export transactions</zn-checkbox>
</zn-checkbox-group>

Label with Tooltip

Use the label-tooltip attribute to add text that appears in a tooltip triggered by an info icon next to the label.

Initiate outbound transfers Approve outbound transfers Export transactions 
<zn-checkbox-group name="a" label="Financial products permissions" help-text="Outbound transfers require separate initiators and approvers" label-tooltip="These apply to cash account only">
  <zn-checkbox value="initiate-outbound">Initiate outbound transfers</zn-checkbox>
  <zn-checkbox value="approve-outbound">Approve outbound transfers </zn-checkbox>
  <zn-checkbox value="export">Export transactions</zn-checkbox>
</zn-checkbox-group>

Horizontal Checkbox Group

Use the horizontal attribute to lay out multiple checkbox items horizontally.

Manage transfers Export transactions 
<zn-checkbox-group name="a" id="permissions" label="Financial products permissions" horizontal>
  <zn-checkbox value="manage-transfers">Manage transfers</zn-checkbox>
  <zn-checkbox value="export">Export transactions</zn-checkbox>
</zn-checkbox-group>

<style>
  zn-checkbox-group[id="permissions"] {
    container-type: inline-size;
    container-name: permissions;
  }

  @container permissions (max-width: 400px) {
    zn-checkbox-group[id="permissions"]::part(form-control-input) {
      flex-direction: column;
    }
  }
</style>

Contained Checkbox Group

Use the contained attribute to draw a card-like container around each checkbox item in the checkbox group. This style is useful for giving more emphasis to the list of options.

This option can be combined with the horizontal attribute.

Initiate outbound transfers Approve outbound transfers Export transactions

Initiate outbound transfers Approve outbound transfers 
<zn-checkbox-group name="a" label="Financial products permissions" help-text="Outbound transfers require separate initiators and approvers" contained>
  <zn-checkbox value="initiate-outbound">Initiate outbound transfers</zn-checkbox>
  <zn-checkbox value="approve-outbound">Approve outbound transfers </zn-checkbox>
  <zn-checkbox value="export">Export transactions</zn-checkbox>
</zn-checkbox-group>
<br/>
<br/>
<zn-checkbox-group name="b" label="Financial products permissions" help-text="Outbound transfers require separate initiators and approvers" contained horizontal>
  <zn-checkbox value="initiate-outbound">Initiate outbound transfers</zn-checkbox>
  <zn-checkbox value="approve-outbound">Approve outbound transfers </zn-checkbox>
</zn-checkbox-group>

Disabling Options

Checkboxes can be disabled by adding the disabled attribute to the respective options inside the checkbox group.

Initiate outbound transfers Approve outbound transfers Export transactions 
<zn-checkbox-group name="a"  label="Financial products permissions" help-text="Exporting is currently disabled for all users" required>
  <zn-checkbox value="initiate-outbound">Initiate outbound transfers</zn-checkbox>
  <zn-checkbox value="approve-outbound">Approve outbound transfers </zn-checkbox>
  <zn-checkbox value="export" disabled>Export transactions</zn-checkbox>
</zn-checkbox-group>

Validation

Set the required attribute to make selecting at least one option mandatory. If at least one value has not been selected, it will prevent the form from submitting and display an error message.

Option 1 Option 2 Option 3
Submit 
<form class="validation">
  <zn-checkbox-group name="a" label="Select at least one option" required>
    <zn-checkbox value="option-1">Option 1</zn-checkbox>
    <zn-checkbox value="option-2">Option 2</zn-checkbox>
    <zn-checkbox value="option-3">Option 3</zn-checkbox>
  </zn-checkbox-group>
  <br />
  <zn-button type="submit" variant="primary">Submit</zn-button>
</form>

<script type="module">
  const form = document.querySelector('.validation');

  // Wait for controls to be defined before attaching form listeners
  await Promise.all([
    customElements.whenDefined('zn-checkbox-group'),
  ]).then(() => {
    form.addEventListener('submit', event => {
      event.preventDefault();
      alert('All fields are valid!');
    });
  });
</script>

Custom Validity

Use the setCustomValidity() method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.

You can optionally choose me I’m optional too You must choose me
Submit 
<form class="custom-validity">
  <zn-checkbox-group name="a" label="Select the third option" required>
    <zn-checkbox value="option-1">You can optionally choose me</zn-checkbox>
    <zn-checkbox value="option-2">I'm optional too</zn-checkbox>
    <zn-checkbox value="option-3">You must choose me</zn-checkbox>
  </zn-checkbox-group>
  <br />
  <zn-button type="submit" variant="primary">Submit</zn-button>
</form>

<script type="module">
  const form = document.querySelector('.custom-validity');
  const checkboxGroup = form.querySelector('zn-checkbox-group');
  const errorMessage = 'You must choose the last option';

  // Set initial validity as soon as the element is defined
  customElements.whenDefined('zn-checkbox').then(() => {
    checkboxGroup.setCustomValidity(errorMessage);
  });

  // Update validity when a selection is made
  form.addEventListener('zn-change', () => {
    const isValid = checkboxGroup.value.some(value => value.includes('option-3'));
    checkboxGroup.setCustomValidity(isValid ? '' : errorMessage);
  });

  // Wait for controls to be defined before attaching form listeners
  await Promise.all([
    customElements.whenDefined('zn-checkbox-group'),
  ]).then(() => {
    form.addEventListener('submit', event => {
      event.preventDefault();
      alert('All fields are valid!');
    });
  });
</script>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.0/dist/components/checkbox-group/checkbox-group.js"></script>

To import this component from the CDN using a JavaScript import: 

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

To import this component using a bundler:

import '@kubex/zinc/dist/components/checkbox-group/checkbox-group.js';

Slots

Name Description
(default) The default slot where <zn-checkbox> elements are placed.
label The checkbox group’s label. Required for proper accessibility. Alternatively, you can use the label attribute.
label-tooltip Used to add text that is displayed in a tooltip next to the label. Alternatively, you can use the label-tooltip attribute.
help-text Text that describes how to use the checkbox group. Alternatively, you can use the help-text attribute.

Learn more about using slots.

Properties

Name Description Reflects Type Default
label The checkbox group’s label. Required for proper accessibility. If you need to display HTML, use the label slot instead. string ''
labelTooltip
label-tooltip 		Text that appears in a tooltip next to the label. If you need to display HTML in the tooltip, use the label-tooltip slot instead. string ''
helpText
help-text 		The checkbox groups’s help text. If you need to display HTML, use the help-text slot instead. string ''
name The name of the checkbox group, submitted as a name/value pair with form data. string ''
value The current value of the checkbox group, submitted as a name/value pair with form data. string[] []
size The checkbox group’s size. This size will be applied to all child checkboxes. 'small' | 'medium' | 'large' 'medium'
horizontal The checkbox group’s orientation. Changes the group’s layout from the default (vertical) to horizontal. boolean false
contained The checkbox group’s style. Changes the group’s style from the default (plain) style to the ‘contained’ style. This style will be applied to all child checkboxes. boolean false
form By default, form controls are associated with the nearest containing <form> element. This attribute allows you to place the form control outside of a form and associate it with the form that has this id. The form must be in the same document or shadow root for this to work. string ''
required Ensures at least one child checkbox is checked before allowing the containing form to submit. boolean false
validity Gets the validity state object - -
validationMessage Gets the validation message - -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
zn-change Emitted when the checkbox group’s selected value changes. -
zn-input Emitted when the checkbox group receives user input. -
zn-invalid Emitted when the form control has been checked for validity and its constraints aren’t satisfied. -

Learn more about events.

Methods

Name Description Arguments
checkValidity() Checks for validity but does not show a validation message. Returns true when valid and false when invalid. -
getForm() Gets the associated form, if one exists. -
reportValidity() Checks for validity and shows the browser’s validation message if the control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message:

Learn more about methods.

Parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label’s wrapper.
form-control-input The input’s wrapper.
form-control-help-text The help text’s wrapper.

Learn more about customizing CSS parts.