CheckboxGroup

A checkbox group allows a user to select one or more values from a list of items through multiple checkboxes.

Install	`yarn add @diallink-corp/convergo-react-checkbox`
Version	4.1.2
Usage	import {CheckboxGroup} from '@diallink-corp/convergo-react-checkbox'

Uncontrolled Value

By default, the CheckboxGroup component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultValue to set a value by default.

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
>
  <Checkbox value="productUpdates" label="Product Updates" />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox value="promotionalCampaigns" label="Promotional Campaigns" />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={[
    'productUpdates',
    'companyNews'
  ]}
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a value prop as well as an onChange handler to modify the value when the user checks the checkboxes.

function Example() {
  const [selected, setSelected] = useState(['productUpdates', 'companyNews']);

  return (
    <div>
      <CheckboxGroup
        label="Newsletters"
        value={selected}
        onChange={setSelected}
      >
        <Checkbox value="productUpdates" label="Product Updates" />
        <Checkbox value="companyNews" label="Company News" />
        <Checkbox value="promotionalCampaigns" label="Promotional Campaigns" />
      </CheckboxGroup>

      <div>Selected Values: {selected.join(', ')}</div>
    </div>
  );
}

function Example() {
  const [selected, setSelected] = useState([
    'productUpdates',
    'companyNews'
  ]);

  return (
    <div>
      <CheckboxGroup
        label="Newsletters"
        value={selected}
        onChange={setSelected}
      >
        <Checkbox
          value="productUpdates"
          label="Product Updates"
        />
        <Checkbox
          value="companyNews"
          label="Company News"
        />
        <Checkbox
          value="promotionalCampaigns"
          label="Promotional Campaigns"
        />
      </CheckboxGroup>

      <div>Selected Values: {selected.join(', ')}</div>
    </div>
  );
}

function Example() {
  const [
    selected,
    setSelected
  ] = useState([
    'productUpdates',
    'companyNews'
  ]);

  return (
    <div>
      <CheckboxGroup
        label="Newsletters"
        value={selected}
        onChange={setSelected}
      >
        <Checkbox
          value="productUpdates"
          label="Product Updates"
        />
        <Checkbox
          value="companyNews"
          label="Company News"
        />
        <Checkbox
          value="promotionalCampaigns"
          label="Promotional Campaigns"
        />
      </CheckboxGroup>

      <div>
        Selected Values:
        {' '}
        {selected.join(
          ', '
        )}
      </div>
    </div>
  );
}

Labeling

A CheckboxGroup component should be labeled with a visual text through the label prop. If the CheckboxGroup does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<CheckboxGroup label='Newsletters'>
  <Checkbox value="productUpdates" label='Product Updates' />
  <Checkbox value="companyNews" label='Company News' />
  <Checkbox value="promotionalCampaigns" label='Promotional Campaigns' />
</CheckboxGroup>

<CheckboxGroup label="Newsletters">
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup label="Newsletters">
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of the CheckboxGroup component is displayed on the left side of the input. For right-to-left (RTL) languages, such as Arabic, this is flipped. You can control the position of the label through the labelPlacement prop.

<CheckboxGroup label='Newsletters' labelPlacement='top end'>
  <Checkbox value="productUpdates" label='Product Updates' />
  <Checkbox value="companyNews" label='Company News' />
  <Checkbox value="promotionalCampaigns" label='Promotional Campaigns' />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  labelPlacement="top end"
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  labelPlacement="top end"
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Label Position

By default, the label of the CheckboxGroup component is displayed above the input. With the labelPlacement prop this placement can be adjusted to be on the side of the input.

<CheckboxGroup label='Newsletters' labelPlacement='side start'>
  <Checkbox value="productUpdates" label='Product Updates' />
  <Checkbox value="companyNews" label='Company News' />
  <Checkbox value="promotionalCampaigns" label='Promotional Campaigns' />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  labelPlacement="side start"
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  labelPlacement="side start"
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Required

To indicate to the user that the CheckboxGroup is required you can use the isRequired prop.

<CheckboxGroup label='Newsletters' isRequired>
  <Checkbox value="productUpdates" label='Product Updates' />
  <Checkbox value="companyNews" label='Company News' />
  <Checkbox value="promotionalCampaigns" label='Promotional Campaigns' />
</CheckboxGroup>

<CheckboxGroup label="Newsletters" isRequired>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  isRequired
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Validation

The CheckboxGroup component has built-in accessible validation support. To indicate whether the group is valid or not you can use the errorMessage prop.

function Example() {
  const [selected, setSelected] = useState(['productUpdates']);

  const isValid = selected.length >= 2;

  return (
    <CheckboxGroup 
      label='Newsletters' 
      value={selected} 
      onChange={setSelected} 
      errorMessage={!isValid && 'You need to select atleast 2 checkboxes.'}
    >
      <Checkbox value="productUpdates" label='Product Updates' />
      <Checkbox value="companyNews" label='Company News' />
      <Checkbox value="promotionalCampaigns" label='Promotional Campaigns' />
    </CheckboxGroup>
  );
}

function Example() {
  const [selected, setSelected] = useState([
    'productUpdates'
  ]);

  const isValid = selected.length >= 2;

  return (
    <CheckboxGroup
      label="Newsletters"
      value={selected}
      onChange={setSelected}
      errorMessage={!isValid &&
        'You need to select atleast 2 checkboxes.'}
    >
      <Checkbox
        value="productUpdates"
        label="Product Updates"
      />
      <Checkbox value="companyNews" label="Company News" />
      <Checkbox
        value="promotionalCampaigns"
        label="Promotional Campaigns"
      />
    </CheckboxGroup>
  );
}

function Example() {
  const [
    selected,
    setSelected
  ] = useState([
    'productUpdates'
  ]);

  const isValid =
    selected.length >= 2;

  return (
    <CheckboxGroup
      label="Newsletters"
      value={selected}
      onChange={setSelected}
      errorMessage={!isValid &&
        'You need to select atleast 2 checkboxes.'}
    >
      <Checkbox
        value="productUpdates"
        label="Product Updates"
      />
      <Checkbox
        value="companyNews"
        label="Company News"
      />
      <Checkbox
        value="promotionalCampaigns"
        label="Promotional Campaigns"
      />
    </CheckboxGroup>
  );
}

Description

The CheckboxGroup supports an optional description that further explains the purpose of the field.

function Example() {
  const [selected, setSelected] = useState(['productUpdates']);

  return (
    <CheckboxGroup 
      label='Newsletters' 
      value={selected} 
      onChange={setSelected} 
      description='Select all newsletters you would like to receive.'
    >
      <Checkbox value="productUpdates" label='Product Updates' />
      <Checkbox value="companyNews" label='Company News' />
      <Checkbox value="promotionalCampaigns" label='Promotional Campaigns' />
    </CheckboxGroup>
  );
}

function Example() {
  const [selected, setSelected] = useState([
    'productUpdates'
  ]);

  return (
    <CheckboxGroup
      label="Newsletters"
      value={selected}
      onChange={setSelected}
      description="Select all newsletters you would like to receive."
    >
      <Checkbox
        value="productUpdates"
        label="Product Updates"
      />
      <Checkbox value="companyNews" label="Company News" />
      <Checkbox
        value="promotionalCampaigns"
        label="Promotional Campaigns"
      />
    </CheckboxGroup>
  );
}

function Example() {
  const [
    selected,
    setSelected
  ] = useState([
    'productUpdates'
  ]);

  return (
    <CheckboxGroup
      label="Newsletters"
      value={selected}
      onChange={setSelected}
      description="Select all newsletters you would like to receive."
    >
      <Checkbox
        value="productUpdates"
        label="Product Updates"
      />
      <Checkbox
        value="companyNews"
        label="Company News"
      />
      <Checkbox
        value="promotionalCampaigns"
        label="Promotional Campaigns"
      />
    </CheckboxGroup>
  );
}

Contextual Help

To offer the user contextual help, the CheckboxGroup supports passing a contextualHelp prop, that accepts a ReactNode.

<CheckboxGroup
  label='Newsletters' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
>
  <Checkbox value="productUpdates" label='Product Updates' />
  <Checkbox value="companyNews" label='Company News' />
  <Checkbox value="promotionalCampaigns" label='Promotional Campaigns' />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Disabled

The CheckboxGroup component can be disabled via the isDisabled prop.

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
  isDisabled
>
  <Checkbox value="productUpdates" label="Product Updates" />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox value="promotionalCampaigns" label="Promotional Campaigns" />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
  isDisabled
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={[
    'productUpdates',
    'companyNews'
  ]}
  isDisabled
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Read Only

The CheckboxGroup component can be marked as read only via the isReadOnly prop.

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
  isReadOnly
>
  <Checkbox value="productUpdates" label="Product Updates" />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox value="promotionalCampaigns" label="Promotional Campaigns" />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
  isReadOnly
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={[
    'productUpdates',
    'companyNews'
  ]}
  isReadOnly
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Vertical Orientation

By default, the CheckboxGroup will align all checkboxes in a vertical orientation, which stacks all checkboxes on top of each other.

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
  orientation="vertical"
>
  <Checkbox value="productUpdates" label="Product Updates" />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox value="promotionalCampaigns" label="Promotional Campaigns" />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
  orientation="vertical"
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={[
    'productUpdates',
    'companyNews'
  ]}
  orientation="vertical"
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Horizontal Orientation

The CheckboxGroup also supports a horizontal orientation, which positions the checkboxes side by side.

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
  orientation="horizontal"
>
  <Checkbox value="productUpdates" label="Product Updates" />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox value="promotionalCampaigns" label="Promotional Campaigns" />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={['productUpdates', 'companyNews']}
  orientation="horizontal"
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox value="companyNews" label="Company News" />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

<CheckboxGroup
  label="Newsletters"
  defaultValue={[
    'productUpdates',
    'companyNews'
  ]}
  orientation="horizontal"
>
  <Checkbox
    value="productUpdates"
    label="Product Updates"
  />
  <Checkbox
    value="companyNews"
    label="Company News"
  />
  <Checkbox
    value="promotionalCampaigns"
    label="Promotional Campaigns"
  />
</CheckboxGroup>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.