index.md

Checkbox Group Field

Provides a checkbox group to be used within forms. It yields CheckboxFields back to the consumer so they can render as many checkboxes as needed with built-in state tracking for the selected values.

Yielded Items

• CheckboxField: An underlying CheckboxField component. All arguments and attributes of CheckboxField can be supplied (e.g., @isDisabled, @hint, etc.). To give each option a unique value, use the @value argument.

Label

Required.

Use either the @label component argument or the :label named block.

Provide a string to the @label component argument or content to the :label named block to render into the legend of the fieldset.

@label

<Form::Fields::CheckboxGroup
  @label='Label here'
  @name='options'
  @value={{this.groupValue}}
  @onChange={{this.updateValue}}
/>

:label

<Form::Fields::CheckboxGroup
  @name='options'
  @value={{this.groupValue}}
  @onChange={{this.updateValue}}
>
  {{!-- default block is required here when using :label --}}
  <:default as |group|>
    {{!-- render checkboxes here --}}
  </:default>
  <:label>Here is a label <IconButton><Tooltip /><IconButton></:label>
</Form::Fields::CheckboxGroup>

Hint

Optional.

Use either the @hint component argument or the :hint named block.

Provide a string to the @hint component argument or content to :hint named block to render into the Hint section.

@hint

<Form::Fields::CheckboxGroup
  @hint='Here is a hint'
  @name='options'
  @value={{this.groupValue}}
  @onChange={{this.updateValue}}
/>

:hint

<Form::Fields::CheckboxGroup
  @name='options'
  @value={{this.groupValue}}
  @onChange={{this.updateValue}}
>
  {{! default block is required here when using :hint}}
  <:default as |group|>
    {{! render checkboxes here }}
  </:default>
  <:hint>Here is a hint <Link to='somewhere'>Link</Link></:hint>
</Form::Fields::CheckboxGroup>

Error

Optional. Provide a string to @error to render the text into the Error section of the fieldset.

Value and onChange

To tie into the input event when a checkbox is clicked, provide @onChange. @onChange will return two arguments:

1. an array containing the selected values
2. the raw event object

A @value argument to the CheckboxGroupField is used to determine which of the checkboxes is currently selected. It does so by comparing @value provided to the CheckboxGroupField to each @value of the checkbox. When an @onChange event occurs, it's most common to update the @value argument to the newly selected values as shown in the example below.

<Form::Fields::CheckboxGroup
  @label='Label'
  @name='options'
  @value={{this.groupValue}}
  @onChange={{this.updateValue}}
  as |group|
>
  <group.CheckboxField @label='Option 1' @value='option-1' />
  <group.CheckboxField @label='Option 2' @value='option-2' />
</Form::Fields::CheckboxGroup>

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { tracked } from '@glimmer/tracking';

export default class extends Component {
  @tracked groupValue = [];

  @action
  updateValue(value) {
    this.groupValue = value;
  }
}

Disabled State

Fieldset

To disable the fieldset and all child checkboxes, set the @isDisabled argument directly on the checkbox group field.

<Form::Fields::CheckboxGroup
  @label='Label'
  @name='options'
  @value={{this.groupValue}}
  @onChange={{this.updateValue}}
  @isDisabled={{true}}
  as |group|
>
  <!-- This will now be disabled as well! -->
  <group.CheckboxField @label='Option 1' @value='option-1' />
</Form::Fields::CheckboxGroup>

Individual Checkboxes

To disable individual checkbox fields, set the @isDisabled argument directly on the checkbox field.

<Form::Fields::CheckboxGroup
  @label='Label'
  @name='options'
  @value={{this.groupValue}}
  @onChange={{this.updateValue}}
  as |group|
>
  <group.CheckboxField
    @label='Option 1'
    @value='option-1'
    @isDisabled={{true}}
  />
</Form::Fields::CheckboxGroup>

Attributes and Modifiers

Consumers have direct access to the underlying checkbox element, so all attributes are supported. Modifiers can also be added directly to individual radio fields.

All UI States

CheckboxGroupField with label

CheckboxGroupField with label and hint

CheckboxGroupField with label block and hint block

<:default as |group|> <:label>Label <:hint>Select an option link

CheckboxGroupField with label and error

CheckboxGroupField with label, hint, and error

CheckboxGroupField with label and isDisabled

CheckboxGroupField with label, hint, and isDisabled

CheckboxGroupField with label and multiple errors