Checkbox

yarn add @clayui/form

A checkbox is a component that lets the user select the value that is written in its corresponding text label. A user can select multiple checkboxes from a group at the same time.

Stable 3.10.0 View in Lexicon CHANGELOG

Read Only
Container Props
Label
Inline
Indeterminate
API

Use checked property to check or not the checkbox.

To set a callback function when the value of the checkbox is changed, use onChange property. See the following example:

import {ClayCheckbox} from '@clayui/form';

import {ClayCheckbox} from '@clayui/form';

const Component = () => {
  const [value, setValue] = useState(false);

  return (
    <ClayCheckbox checked={value} onChange={() => setValue(val => !val)} />
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState(false);
  return (
    <ClayCheckbox checked={value} onChange={() => setValue(val => !val)} />
  );
};
render(<Component />);

Here you can see some options or ideas on how to extend our Checkbox component to fit your use:

Read Only

If you want a checkbox without actions on change(or just not use onChange property), use readOnly property.

import {ClayCheckbox} from '@clayui/form';

import {ClayCheckbox} from '@clayui/form';

const Component = () => {
  return (
    <ClayCheckbox aria-label="hello! Can you see me?" checked={true} readOnly />
  );
};

render(<Component />);

const Component = () => {
  return (
    <ClayCheckbox aria-label="hello! Can you see me?" checked={true} readOnly />
  );
};
render(<Component />);

Container Props

If you want to modify the container that wraps the checkbox, use containerProps:

import {ClayCheckbox} from '@clayui/form';

import {ClayCheckbox} from '@clayui/form';

const Component = () => {
  const [value, setValue] = useState(false);

  const data = {
    id: "test"
  };

  return (
    <ClayCheckbox
      aria-label="I'm checked indefinitely"
      checked={true}
      containerProps={data}
      onChange={() => setValue(val => !val)}
    />
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState(false);
  const data = {
    id: "test"
  };
  return (
    <ClayCheckbox
      aria-label="I'm checked indefinitely"
      checked={true}
      containerProps={data}
      onChange={() => setValue(val => !val)}
    />
  );
};
render(<Component />);

Label

Use label property to describe what the checkbox is for.

Option 1

import {ClayCheckbox} from '@clayui/form';

import {ClayCheckbox} from '@clayui/form';

const Component = () => {
  const [value, setValue] = useState(false);

  return (
    <ClayCheckbox
      aria-label="Option 1"
      checked={value}
      onChange={() => setValue(val => !val)}
      label="Option 1"
    />
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState(false);
  return (
    <ClayCheckbox
      aria-label="Option 1"
      checked={value}
      onChange={() => setValue(val => !val)}
      label="Option 1"
    />
  );
};
render(<Component />);

Inline

Group checkboxes on the same horizontal row by using inline property.

Option 1

Option 2

Option 3

import {ClayCheckbox} from '@clayui/form';

import {ClayCheckbox} from '@clayui/form';

const Component = () => {
  const [value, setValue] = useState(false);

  return (
    <>
      <ClayCheckbox
        aria-label="Option 1"
        checked={value}
        onChange={() => setValue(val => !val)}
        label="Option 1"
        inline
      />
      <ClayCheckbox
        aria-label="Option 2"
        checked={value}
        onChange={() => setValue(val => !val)}
        label="Option 2"
        inline
      />
      <ClayCheckbox
        aria-label="Option 3"
        checked={value}
        onChange={() => setValue(val => !val)}
        label="Option 3"
        inline
      />
    </>
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState(false);
  return (
    <>
      <ClayCheckbox
        aria-label="Option 1"
        checked={value}
        onChange={() => setValue(val => !val)}
        label="Option 1"
        inline
      />
      <ClayCheckbox
        aria-label="Option 2"
        checked={value}
        onChange={() => setValue(val => !val)}
        label="Option 2"
        inline
      />
      <ClayCheckbox
        aria-label="Option 3"
        checked={value}
        onChange={() => setValue(val => !val)}
        label="Option 3"
        inline
      />
    </>
  );
};
render(<Component />);

Indeterminate

Use indeterminate property for making the checkbox indeterminate.

import {ClayCheckbox} from '@clayui/form';

import {ClayCheckbox} from '@clayui/form';

const Component = () => {
  const [value, setValue] = useState(false);

  return (
    <ClayCheckbox
      aria-label="I'm indeterminate"
      checked={value}
      onChange={() => setValue(val => !val)}
      indeterminate
    />
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState(false);
  return (
    <ClayCheckbox
      aria-label="I'm indeterminate"
      checked={value}
      onChange={() => setValue(val => !val)}
      indeterminate
    />
  );
};
render(<Component />);

API

Property	Type	Required	Default	Description
checked	boolean	true		Flag to indicate if input is checked or not.
containerProps	React.HTMLAttributes<HTMLDivElement>	false	{}	Props to add to the outer most container.
indeterminate	boolean	false	false	Flag to indicate that checkbox is in an indeterminate state.
inline	boolean	false		Flag to display element `inline`.
label	React.ReactText	false		Text describes what the checkbox is for.
onChange	(e: React.ChangeEvent<HTMLInputElement>) => void	true		Callback for when checkbox value is changed

Default
Inline
Disabled
Without labels
Custom

Don't forget to check WAI-ARIA accessibility pratices for checkboxes when writting your markup.

Default checkboxes and radios are improved upon with the help of .form-check, a single class for both input types that improves the layout and behavior of their HTML elements. Checkboxes are for selecting one or several options in a list, while radios are for selecting one option from many. By Bootstrap

Default

By default, any number of checkboxes and radios that are immediate sibling will be vertically stacked and appropriately spaced with .form-check.

Checkboxes

Default checkbox

Disabled checkbox

<div class="form-check">
	<input
		class="form-check-input"
		type="checkbox"
		value=""
		id="defaultCheck1"
	/>
	<label class="form-check-label" for="defaultCheck1">
		Default checkbox
	</label>
</div>
<div class="form-check">
	<input
		class="form-check-input"
		type="checkbox"
		value=""
		id="defaultCheck2"
		disabled
	/>
	<label class="form-check-label" for="defaultCheck2">
		Disabled checkbox
	</label>
</div>

Radios

Default radio

Second default radio

Disabled radio

<div class="form-check">
	<input
		class="form-check-input"
		type="radio"
		name="exampleRadios"
		id="exampleRadios1"
		value="option1"
		checked
	/>
	<label class="form-check-label" for="exampleRadios1">
		Default radio
	</label>
</div>
<div class="form-check">
	<input
		class="form-check-input"
		type="radio"
		name="exampleRadios"
		id="exampleRadios2"
		value="option2"
	/>
	<label class="form-check-label" for="exampleRadios2">
		Second default radio
	</label>
</div>
<div class="form-check">
	<input
		class="form-check-input"
		type="radio"
		name="exampleRadios"
		id="exampleRadios3"
		value="option3"
		disabled
	/>
	<label class="form-check-label" for="exampleRadios3">
		Disabled radio
	</label>
</div>

Inline

Group checkboxes or radios on the same horizontal row by adding .form-check-inline to any .form-check.

Checkbox

<div class="form-check form-check-inline">
	<label class="form-check-label">
		<input
			class="form-check-input"
			type="checkbox"
			value=""
			id="inlineCheckbox1"
		/>
		<span class="form-check-label-text">1</span>
	</label>
</div>
<div class="form-check form-check-inline">
	<label class="form-check-label">
		<input
			class="form-check-input"
			type="checkbox"
			value=""
			id="inlineCheckbox2"
			disabled
		/>
		<span class="form-check-label-text">2</span>
	</label>
</div>

Radio

<div class="form-check form-check-inline">
	<label class="form-check-label">
		<input
			class="form-check-input"
			type="radio"
			name="inlineRadioOptions"
			value="option1"
			id="inlineRadio1"
		/>
		<span class="form-check-label-text">1</span>
	</label>
</div>
<div class="form-check form-check-inline">
	<label class="form-check-label">
		<input
			class="form-check-input"
			type="radio"
			name="inlineRadioOptions"
			value="option2"
			id="inlineRadio2"
			disabled
		/>
		<span class="form-check-label-text">2</span>
	</label>
</div>

Disabled

Disable checkboxes or radios by adding a disabled prop.

Toggle this custom radio

Check this custom checkbox

<div class="custom-control custom-radio">
	<label>
		<input
			disabled=""
			class="custom-control-input"
			id="radio1"
			name="customDisabledRadio"
			type="radio"
		/>
		<span class="custom-control-label">
			<span class="custom-control-label-text"
				>Toggle this custom radio</span
			>
		</span>
	</label>
</div>
<div class="custom-control custom-checkbox">
	<label>
		<input
			disabled=""
			class="custom-control-input"
			type="checkbox"
			id="customDisabledCheck1"
		/>
		<span class="custom-control-label">
			<span class="custom-control-label-text"
				>Check this custom checkbox</span
			>
		</span>
	</label>
</div>

Without labels

Remember to still provide some form of label for assistive technologies (for instance, using aria-label).

<div class="form-check">
	<label class="form-check-label">
		<input
			class="form-check-input"
			type="checkbox"
			id="withoutLabelCheckbox"
			value=""
		/>
	</label>
</div>
<div class="form-check">
	<label class="form-check-label">
		<input
			class="form-check-input"
			type="checkbox"
			id="withoutLabelCheckbox1"
			value=""
		/>
	</label>
</div>

Custom

The two ways for you to structure the marking of a Checkbox and Radio:

It is packaged in a classless <label> and <label class="custom-control-label"/> is replaced by <span>:

<div class="custom-control custom-checkbox">
	<label>
		<input class="custom-control-input" type="checkbox" id="customCheck1" />
		<span class="custom-control-label">
			<span class="custom-control-label-text"
				>Check this custom checkbox</span
			>
		</span>
	</label>
</div>

Using the id binding engine with <label />and <input />.

<div class="custom-control custom-checkbox">
	<input class="custom-control-input" type="checkbox" id="customCheck2" />
	<label class="custom-control-label" for="customCheck2">
		<span class="custom-control-label-text"
			>Check this custom checkbox</span
		>
	</label>
</div>

Checkboxes

Check this custom checkbox

<div class="custom-control custom-checkbox">
	<label>
		<input class="custom-control-input" type="checkbox" id="customCheck1" />
		<span class="custom-control-label">
			<span class="custom-control-label-text"
				>Check this custom checkbox</span
			>
		</span>
	</label>
</div>

Custom checkboxes can also utilize the :indeterminate pseudo class when manually set via JavaScript (there is no available HTML attribute for specifying it).

Indeterminate

Radios

Toggle this custom radio

Or toggle this other custom radio

<div class="custom-control custom-radio">
	<label>
		<input
			checked=""
			class="custom-control-input"
			id="radio1"
			name="customRadio"
			type="radio"
		/>
		<span class="custom-control-label">
			<span class="custom-control-label-text"
				>Toggle this custom radio</span
			>
		</span>
	</label>
</div>
<div class="custom-control custom-radio">
	<label>
		<input
			class="custom-control-input"
			id="radio1"
			name="customRadio"
			type="radio"
		/>
		<span class="custom-control-label">
			<span class="custom-control-label-text"
				>Or toggle this other custom radio</span
			>
		</span>
	</label>
</div>