# Checkbox
Checkbox is a type of control component that allows user to select one or more options from a set. They can also be used alone to switch between on and off.
## Import
```tsx
import { Checkbox } from '@coinbase/cds-web/controls/Checkbox'
```
## Examples
### Basic Usage
Checkbox UI and state management are separated so that you can swap in any form or state code you like.
```jsx live
function BasicCheckbox() {
const [isChecked, setIsChecked] = useState(false);
return (
setIsChecked(e.target.checked)}
checked={isChecked}
>
Subscribe to newsletter
);
}
```
### Custom Layout
If you don't want to use the default label or layout style, you can just not provide `children` to the `Checkbox` component. However, you should think about wrapping the custom label and `Checkbox` in a `` if it makes sense to increase the tap target of the component and allow users to toggle by pressing on the label as well.
```jsx live
function CustomLayoutCheckbox() {
const [isChecked, setIsChecked] = useState(false);
return (
Premium Features
Access to advanced tools and priority support
setIsChecked(e.target.checked)}
checked={isChecked}
/>
);
}
```
### Different States
Checkboxes support various states including disabled and indeterminate.
```jsx live
function CheckboxStates() {
const [checked, setChecked] = useState(false);
const [indeterminate, setIndeterminate] = useState(true);
return (
setChecked(e.target.checked)} checked={checked}>
Normal checkbox
Disabled & unchecked
Disabled & checked
{
setIndeterminate(false);
// Handle the change as needed
}}
>
Indeterminate state
);
}
```
### Custom Colors
Like other control components (i.e. Radio, Switch), you can customize the color of the Checkbox by setting the `controlColor` prop.
```jsx live
function CustomColors() {
const [checked, setChecked] = useState(false);
return (
setChecked((s) => !s)}
checked={checked}
>
Custom control color
);
}
```
For more advanced customization, you can also control the border shape and thickness using `borderRadius` and `borderWidth`, along with `background` and `borderColor`:
```jsx live
function AdvancedCustomColors() {
const [checked, setChecked] = useState(false);
return (
setChecked((s) => !s)}
>
Advanced styling (rounded corners + thick border)
);
}
```
### Multiple Checkboxes
For multiple checkbox scenarios, use [ControlGroup](/components/inputs/ControlGroup) with `role="group"` for better accessibility and state management:
```jsx live
function MultipleCheckboxes() {
const options = [
{ value: 'email', children: 'Email notifications' },
{ value: 'sms', children: 'SMS notifications' },
{ value: 'push', children: 'Push notifications' },
];
const [selectedValues, setSelectedValues] = useState(['email']);
const handleChange = (e) => {
const { value, checked } = e.target;
setSelectedValues((prev) => (checked ? [...prev, value] : prev.filter((v) => v !== value)));
};
return (
> \| Iterable \| ReactPortal` | No | `-` | Label for the control option. |
| `color` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `-` | - |
| `controlColor` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `fgInverse` | Sets the checked/active color of the control. |
| `iconStyle` | `CSSProperties` | No | `-` | Style for the icon element |
| `indeterminate` | `boolean` | No | `-` | Enable indeterminate state. Useful when you want to indicate that sub-items of a control are partially filled. |
| `labelStyle` | `CSSProperties` | No | `-` | Style for the label element |
| `onChange` | `ChangeEventHandler` | No | `-` | - |
| `ref` | `null \| (instance: HTMLInputElement \| null) => void \| RefObject` | No | `-` | - |
| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
| `type` | `number \| color \| button \| search \| time \| image \| text \| hidden \| string & {} \| email \| checkbox \| radio \| tel \| url \| date \| submit \| reset \| datetime-local \| file \| month \| password \| range \| week` | No | `-` | - |
| `value` | `string` | No | `-` | Value of the option. Useful for multiple choice. |