Checkbox

View in Lexicon

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.

installyarn add @clayui/form
versionNPM Version
useimport {ClayCheckbox} from '@clayui/form';

Table of Contents

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:

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import {ClayCheckbox} from '@clayui/form';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(false);

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<ClayCheckbox
					checked={value}
					onChange={() => setValue((val) => !val)}
				/>
			</div>
		</Provider>
	);
}

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

Container Props

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

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import {ClayCheckbox} from '@clayui/form';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(false);

	const data = {
		id: 'test',
	};

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<ClayCheckbox
					aria-label="I'm checked indefinitely"
					checked={true}
					containerProps={data}
					onChange={() => setValue((val) => !val)}
				/>
			</div>
		</Provider>
	);
}

Label

Use label property to describe what the checkbox is for.

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import {ClayCheckbox} from '@clayui/form';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(false);

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<ClayCheckbox
					aria-label="Option 1"
					checked={value}
					onChange={() => setValue((val) => !val)}
					label="Option 1"
				/>
			</div>
		</Provider>
	);
}

Inline

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

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import {ClayCheckbox} from '@clayui/form';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(false);

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<>
					<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
					/>
				</>
			</div>
		</Provider>
	);
}

Indeterminate

Use indeterminate property for making the checkbox indeterminate.

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import {ClayCheckbox} from '@clayui/form';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(false);

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<ClayCheckbox
					aria-label="I'm indeterminate"
					checked={value}
					onChange={() => setValue((val) => !val)}
					indeterminate
				/>
			</div>
		</Provider>
	);
}

API Reference

Checkbox

React.ForwardRefExoticComponent<IProps & React.RefAttributes<HTMLInputElement>>
Parameters
Properties

checked *

boolean

Flag to indicate if input is checked or not.

containerProps

React.HTMLAttributes<HTMLDivElement> | undefined

Props to add to the outer most container.

disabled

boolean | undefined

Props to disable checkbox.

indeterminate

boolean | undefined

Flag to indicate that checkbox is in an indeterminate state.

inline

boolean | undefined

Flag to display element inline.

label

React.ReactText | undefined

Text describes what the checkbox is for.

onChange

((event: React.ChangeEvent<HTMLInputElement>) => void) | undefined

Callback for when checkbox value is changed.

Returns
ReactElement<any, string | JSXElementConstructor<any>> | null
Edit this page on GitHub

Contributors

Matuzalém Teles, Diego Nascimento, Bryce Osterhaus, Krešimir Čoko, Ilza Medeiros

Last edited May 9, 2025 at 6:15:38 AM

Table of Contents