Checkbox Group
Examples
Help text
Hiding the fieldset
Disabling options
Sizing options
Error and success states
Validation
Custom validity
Importing
Slots
Properties
Events
Methods
Parts
Dependencies

Checkbox Group

<mo-checkbox-group> | MOCheckboxGroup

Since 4.2

stable

Checkbox groups are used to group multiple checkboxes so they function as a single form control.

Option 1

Option 2

Option 3

<mo-checkbox-group label="Select an option" name="a" value="1">
  <mo-checkbox value="1">Option 1</mo-checkbox>
  <mo-checkbox value="2">Option 2</mo-checkbox>
  <mo-checkbox value="3">Option 3</mo-checkbox>
</mo-checkbox-group>

import MOCheckbox from '@metsooutotec/modes-web-components/dist/react/checkbox';
import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group';

const App = () => (
  <MOCheckboxGroup label="Select an option" name="a" value="1">
    <MOCheckbox value="1">Option 1</MOCheckbox>
    <MOCheckbox value="2">Option 2</MOCheckbox>
    <MOCheckbox value="3">Option 3</MOCheckbox>
  </MOCheckboxGroup>
);

Examples

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.

Option 1

Option 2

Option 3

<mo-checkbox-group label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
  <mo-checkbox value="1">Option 1</mo-checkbox>
  <mo-checkbox value="2">Option 2</mo-checkbox>
  <mo-checkbox value="3">Option 3</mo-checkbox>
</mo-checkbox-group>

import MOCheckbox from '@metsooutotec/modes-web-components/dist/react/checkbox';
import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group';

const App = () => (
  <MOCheckboxGroup label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
    <MOCheckbox value="1">Option 1</MOCheckbox>
    <MOCheckbox value="2">Option 2</MOCheckbox>
    <MOCheckbox value="3">Option 3</MOCheckbox>
  </MOCheckboxGroup>
);

Hiding the fieldset

Use the hide-fieldset attribute to hide the fieldset styling (border, padding).

Option 1

Option 2

Option 3

<mo-checkbox-group
  hide-fieldset
  label="Select an option"
  help-text="Choose the most appropriate option."
  name="a"
  value="1"
>
  <mo-checkbox value="1">Option 1</mo-checkbox>
  <mo-checkbox value="2">Option 2</mo-checkbox>
  <mo-checkbox value="3">Option 3</mo-checkbox>
</mo-checkbox-group>

import MOCheckbox from '@metsooutotec/modes-web-components/dist/react/checkbox';
import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group';

const App = () => (
  <MOCheckboxGroup
    hideFieldset
    label="Select an option"
    help-text="Choose the most appropriate option."
    name="a"
    value="1"
  >
    <MOCheckbox value="1">Option 1</MOCheckbox>
    <MOCheckbox value="2">Option 2</MOCheckbox>
    <MOCheckbox value="3">Option 3</MOCheckbox>
  </MOCheckboxGroup>
);

Disabling options

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

Option 1

Option 2

Option 3

<mo-checkbox-group label="Select an option" name="a" value="1">
  <mo-checkbox value="1">Option 1</mo-checkbox>
  <mo-checkbox value="2" disabled>Option 2</mo-checkbox>
  <mo-checkbox value="3">Option 3</mo-checkbox>
</mo-checkbox-group>

import MOCheckbox from '@metsooutotec/modes-web-components/dist/react/checkbox';
import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group';

const App = () => (
  <MOCheckboxGroup label="Select an option" name="a" value="1">
    <MOCheckbox value="1">Option 1</MOCheckbox>
    <MOCheckbox value="2" disabled>
      Option 2
    </MOCheckbox>
    <MOCheckbox value="3">Option 3</MOCheckbox>
  </MOCheckboxGroup>
);

Sizing options

The size of Checkboxes will be determined by the Checkbox Group’s size attribute.

Small

Medium

Large

<mo-checkbox-group label="Select an option" size="medium" value="medium" class="checkbox-group-size">
  <mo-checkbox value="small">Small</mo-checkbox>
  <mo-checkbox value="medium">Medium</mo-checkbox>
  <mo-checkbox value="large">Large</mo-checkbox>
</mo-checkbox-group>

<script>
  const checkboxGroup = document.querySelector('.checkbox-group-size');

  checkboxGroup.addEventListener('mo-change', (event) => {
    checkboxGroup.value = event.target.value;
    if (event.target.nodeName === 'MO-CHECKBOX') {
      checkboxGroup.size = event.target.value;
    }
  });
</script>

import { useState } from 'react';
import MOCheckbox from '@metsooutotec/modes-web-components/dist/react/checkbox';
import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group';

const App = () => {
  const [size, setSize] = useState('medium');

  return (
    <>
      <MOCheckboxGroup
        label="Select an option"
        size={size}
        value={size}
        class="checkbox-group-size"
        onMOChange={event => setSize(event.target.value)}
      >
        <MOCheckbox value="small">Small</MOCheckbox>
        <MOCheckbox value="medium">Medium</MOCheckbox>
        <MOCheckbox value="large">Large</MOCheckbox>
      </MOCheckboxGroup>
    </>
  );
};

Checkboxes also have a size attribute. This can be useful in certain compositions, but it will be ignored when used inside of a Checkbox Group.

Error and success states

You can display error and success messages on the group by using the error-text and success-text attributes.

Option 1

Option 2

Option 3

Option 1

Option 2

Option 3

<mo-checkbox-group required label="Error checkboxes" name="a" error-text="Please choose at least one option.">
  <mo-checkbox value="1">Option 1</mo-checkbox>
  <mo-checkbox value="2">Option 2</mo-checkbox>
  <mo-checkbox value="3">Option 3</mo-checkbox>
</mo-checkbox-group>

<br/>

<mo-checkbox-group label="Success checkboxes" name="a" value="2" success-text="This is a success message">
  <mo-checkbox value="1">Option 1</mo-checkbox>
  <mo-checkbox value="2">Option 2</mo-checkbox>
  <mo-checkbox value="3">Option 3</mo-checkbox>
</mo-checkbox-group>

import { useState } from 'react';
import MOCheckbox from '@metsooutotec/modes-web-components/dist/react/checkbox';
import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group';

const App = () => {
  const [errorText, setErrorText] = useState('This is an error message');
  const [successText, setSuccessText] = useState('This is a success message');

  return (
    <>
      <MOCheckboxGroup
        label="Select an option"
        name="a"
        value="1"
        errorText={errorText}
      >
        <MOCheckbox value="1">Option 1</MOCheckbox>
        <MOCheckbox value="2">Option 2</MOCheckbox>
        <MOCheckbox value="3">Option 3</MOCheckbox>
      </MOCheckboxGroup>
      <MOCheckboxGroup
        label="Select an option"
        name="a"
        value="1"
        successText={successText}
      >
        <MOCheckbox value="1">Option 1</MOCheckbox>
        <MOCheckbox value="2">Option 2</MOCheckbox>
        <MOCheckbox value="3">Option 3</MOCheckbox>
      </MOCheckboxGroup>
    </>
  );
};

Validation

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

<form class="validation">
  <mo-checkbox-group id="validation-example" label="Select an option" name="a" required>
    <mo-checkbox value="1">Option 1</mo-checkbox>
    <mo-checkbox value="2">Option 2</mo-checkbox>
    <mo-checkbox value="3">Option 3</mo-checkbox>
  </mo-checkbox-group>
  <br />
  <mo-button type="submit" id="validation-btn" variant="primary">Submit</mo-button>
</form>

<script type="module">
  const form = document.querySelector('.validation');
  const button = document.querySelector('#validation-btn');
  const cbGroup = document.querySelector('#validation-example');

  button.addEventListener('click', () => {
    if (cbGroup.value.length === 0) {
      cbGroup.errorText = "You must choose at least one option."
      cbGroup.successText = ""
    } else {
      cbGroup.errorText = ""
      cbGroup.successText = "You have chosen at least one option."
    }
  })

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

import MOButton from '@metsooutotec/modes-web-components/dist/react/button';
import MOIcon from '@metsooutotec/modes-web-components/dist/react/icon';
import MOCheckbox from '@metsooutotec/modes-web-components/dist/react/checkbox';
import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group';
const App = () => {
  function handleSubmit(event) {
    event.preventDefault();
    alert('All fields are valid!');
  }

  return (
    <form class="custom-validity" onSubmit={handleSubmit}>
      <MOCheckboxGroup label="Select an option" name="a" required>
        <MOCheckbox value="1">
          Option 1
        </MOCheckbox>
        <MOCheckbox value="2">
          Option 2
        </MOCheckbox>
        <MOCheckbox value="3">
          Option 3
        </MOCheckbox>
      </MOCheckboxGroup>
      <br />
      <MOButton type="submit" variant="primary">
        Submit
      </MOButton>
    </form>
  );
};

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.

<form class="custom-validity">
  <mo-checkbox-group label="Select an option" name="a" value="1">
    <mo-checkbox value="1">Not me</mo-checkbox>
    <mo-checkbox value="2">Me neither</mo-checkbox>
    <mo-checkbox value="3">Choose me</mo-checkbox>
  </mo-checkbox-group>
  <br />
  <mo-button type="submit" variant="primary">Submit</mo-button>
</form>

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

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

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

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

import { useEffect, useRef } from 'react';
import MOButton from '@metsooutotec/modes-web-components/dist/react/button';
import MOIcon from '@metsooutotec/modes-web-components/dist/react/icon';
import MOCheckbox from '@metsooutotec/modes-web-components/dist/react/checkbox';
import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group';
const App = () => {
  const checkboxGroup = useRef(null);
  const errorMessage = 'You must choose this option';

  function handleChange() {
    checkboxGroup.current.setCustomValidity(checkboxGroup.current.value === '3' ? '' : errorMessage);
  }

  function handleSubmit(event) {
    event.preventDefault();
    alert('All fields are valid!');
  }

  useEffect(() => {
    checkbox.current.setCustomValidity(errorMessage);
  }, []);

  return (
    <form class="custom-validity" onSubmit={handleSubmit}>
      <MOCheckboxGroup ref={checkboxGroup} label="Select an option" name="a" value="1" onMOChange={handleChange}>
        <MOCheckbox value="1">Not me</MOCheckbox>
        <MOCheckbox value="2">Me neither</MOCheckbox>
        <MOCheckbox value="3">Choose me</MOCheckbox>
      </MOCheckboxGroup>
      <br />
      <MOButton type="submit" variant="primary">
        Submit
      </MOButton>
    </form>
  );
};

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.

Bundler

React

Script

To import this component using a bundler:

import '@metsooutotec/modes-web-components/dist/components/checkbox-group/checkbox-group.js';

To import this component as a React component:

import MOCheckboxGroup from '@metsooutotec/modes-web-components/dist/react/checkbox-group/';

To import this component using a script tag:

<script type="module" src="https://modes-web.metso.com/dist/components/cdn/components/checkbox-group/checkbox-group.js"></script>

Slots

Name	Description
(default)	The default slot where `<mo-checkbox>` elements are placed.
`label`	The checkbox group’s label. Required for proper accessibility. Alternatively, you can use the `label` attribute.
`help-text`	Text that describes how to use the checkbox group. Alternatively, you can use the `help-text` attribute.
`error`	Error text to show when the radio group is in an error state. Alternatively, you can use the `error-text` attribute.
`success`	Success text to show when the radio group is in a success state. Alternatively, you can use the `success-text` attribute.

Learn more about using slots.

Properties

Name	Description	Type	Default
`label`	The checkbox group’s label. Required for proper accessibility. If you need to display HTML, use the `label` 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`	`'option'`
`value`	The current value of the checkbox group, submitted as a name/value pair with form data. The value attribute will be a space-delimited list of values based on the options selected, and the value property will be an array. For this reason, values must not contain spaces.	`string \| string[]`	`''`
`size`	The checkbox group’s size. This size will be applied to all child checkboxes and checkbox buttons.	`'small' \| 'medium' \| 'large'`	`'medium'`
`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 a child checkbox is checked before allowing the containing form to submit.	`boolean`	`false`
`hideFieldset` `hide-fieldset`	Renders the checkbox group without the border and padding.	`boolean`	`false`
`error`	Renders the group in an error state	`boolean`	`false`
`success`	Renders the group in a success state	`boolean`	`false`
`errorText` `error-text`	Error text to show in place of help text when group is invalid.	`string`	`''`
`successText` `success-text`	Success text to show in place of help text when group is valid.	`string`	`''`
`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
`mo-change`	`onMoChange`	Emitted when the checkbox group’s selected value changes.	-
`mo-input`	`onMoInput`	Emitted when the checkbox group receives user input.	-
`mo-invalid`	`onMoInvalid`	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.
`label__base`	The checkbox group label.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

<mo-label>

Ask Rocky (Beta)

Examples

Help text

Hiding the fieldset

Disabling options

Sizing options

Error and success states

Validation

Custom validity

Importing

Slots

Properties

Events

Methods

Parts

Dependencies