Checkbox | iTwinUI

Allows the user to make one or more choices within a list of options.

import * as React from 'react';
import { Checkbox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <Checkbox label='Option 1' defaultChecked />
      <Checkbox label='Option 2' />
      <Checkbox label='Option 3' defaultChecked disabled />
      <Checkbox label='Option 4' disabled />
    </div>
  );
};

A checkbox is a form component, typically accompanied with a label, allowing for the selection of multiple items. A checkbox can be used for selecting one or more options within a list, or to enable / disable / show / hide a feature within the user interface.

A checkbox should not be confused with a toggle switch, which has a similar role but is not appropriate in all scenarios. To learn more about when to use a toggle switch or a checkbox, please read Checkbox vs Toggle Switch by Saadia Minhas.

A checkbox is not interchangeable with a radio. A radio must have at minimum 2 choice options and only one option can be checked. A checkbox, however, can have as many or as few items checked, and can be displayed as standalone or within a group of two or more.

Variants

Default

The default checkboxes are used to turn on and off one or multiple options.

import * as React from 'react';
import { Checkbox } from '@itwin/itwinui-react';

export default () => {
  const [option1, setOption1] = React.useState(false);
  const [option2, setOption2] = React.useState(true);
  const allOptions = option1 && option2;
  const isIndeterminate = !(option1 && option2) && (option1 || option2);

  const onAllChange = (value) => {
    setOption1(value);
    setOption2(value);
  };

  return (
    <div className='demo-container'>
      <Checkbox
        label='Option 1'
        onChange={(event) => onAllChange(event.target.checked)}
        indeterminate={isIndeterminate}
        checked={allOptions}
      />
      <div className='demo-container demo-indented'>
        <Checkbox
          label='Option 1.1'
          checked={option1}
          onChange={(event) => setOption1(event.target.checked)}
        />
        <Checkbox
          label='Option 1.2'
          checked={option2}
          onChange={(event) => setOption2(event.target.checked)}
        />
      </div>
    </div>
  );
};

Visibility

Often times checkboxes are used to visibly turn on and off a layer within a view. If the checkboxes are used for visibility you can use the eyeball variant which uses an eyeball icon instead of a checkmark to reinforce that something is being shown or hidden.

import * as React from 'react';
import { Checkbox } from '@itwin/itwinui-react';

export default () => {
  const [option1, setOption1] = React.useState(false);
  const [option2, setOption2] = React.useState(true);
  const allOptions = option1 && option2;
  const isIndeterminate = !(option1 && option2) && (option1 || option2);

  const onAllChange = (value) => {
    setOption1(value);
    setOption2(value);
  };

  return (
    <div className='demo-container'>
      <Checkbox
        label='Option 1'
        onChange={(event) => onAllChange(event.target.checked)}
        indeterminate={isIndeterminate}
        checked={allOptions}
        variant='eyeball'
      />
      <div className='demo-container demo-indented'>
        <Checkbox
          label='Option 1.1'
          checked={option1}
          onChange={(event) => setOption1(event.target.checked)}
          variant='eyeball'
        />
        <Checkbox
          label='Option 1.2'
          checked={option2}
          onChange={(event) => setOption2(event.target.checked)}
          variant='eyeball'
        />
      </div>
    </div>
  );
};

Usage

With input group

Checkboxes are often paired with the input group which gives many additional options.

import * as React from 'react';
import { Checkbox, InputGroup } from '@itwin/itwinui-react';

export default () => {
  return (
    <InputGroup label='What are your hobbies?'>
      <Checkbox label='Sports' defaultChecked />
      <Checkbox label='Writing' />
      <Checkbox label='Cooking' />
      <Checkbox label='Arts and crafts' />
    </InputGroup>
  );
};

Indeterminate

When a main option has associated sub-options, parent-child checkboxes are used. They make selecting/unselecting the entirety of a list of options easier if all or neither of them apply to a user’s choice. If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox.

import * as React from 'react';
import { Checkbox } from '@itwin/itwinui-react';

export default () => {
  const [option1, setOption1] = React.useState(false);
  const [option2, setOption2] = React.useState(true);
  const allOptions = option1 && option2;
  const isIndeterminate = !(option1 && option2) && (option1 || option2);

  const onAllChange = (value) => {
    setOption1(value);
    setOption2(value);
  };

  return (
    <div className='demo-container'>
      <Checkbox
        label='Option 1'
        onChange={(event) => onAllChange(event.target.checked)}
        indeterminate={isIndeterminate}
        checked={allOptions}
      />
      <div className='demo-container demo-indented'>
        <Checkbox
          label='Option 1.1'
          checked={option1}
          onChange={(event) => setOption1(event.target.checked)}
        />
        <Checkbox
          label='Option 1.2'
          checked={option2}
          onChange={(event) => setOption2(event.target.checked)}
        />
      </div>
    </div>
  );
};

Loading

If the checkbox is performing an action immediately after being checked, it may take the user interface some time before reflecting that change. While waiting for that change to occur you can display a loading checkbox so the user understands that the action taken has yet to be applied.

import * as React from 'react';
import { Checkbox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <Checkbox label='Enable 2D mode' defaultChecked />
      <Checkbox label='Enable 3D mode' isLoading />
      <Checkbox label='Enable 4D mode' disabled />
    </div>
  );
};

Statuses

If you ever need to display the status or severity of a single checkbox, you can apply a status on the checkbox. Before doing so, consider if using an input group with a status message makes more sense.

import * as React from 'react';
import { Checkbox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <Checkbox label='Default' />
      <Checkbox label='Positive' status='positive' />
      <Checkbox label='Warning' status='warning' />
      <Checkbox label='Negative' status='negative' />
    </div>
  );
};

Props

Prop	Description	Default
label	Text that will be shown next to the checkbox. ReactNode
indeterminate	Allow checkbox to be indeterminate. boolean	false
status	Status of checkbox. "positive" \| "warning" \| "negative"
variant	Type of checkbox, regular or eyeball checkbox that is used for visibility. "default" \| "eyeball"	'default'
isLoading	Display a loading state. boolean	false
wrapperProps	Passes properties for checkbox wrapper. DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>
labelProps	Passes properties for checkbox label. DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>
as	"symbol" \| "object" \| "input" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| "br" \| "button" \| ... 159 more ... \| FunctionComponent<...>