# @leafygreen-ui/checkbox

> LeafyGreen UI Kit Checkbox

Latest version **18.1.6** (published 2026-10-02) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @leafygreen-ui/checkbox
pnpm add @leafygreen-ui/checkbox
yarn add @leafygreen-ui/checkbox
bun add @leafygreen-ui/checkbox
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 18.1.6 |
| Published | 2026-10-02 |
| First published | 2019-04-17 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 9 |
| Unpacked size | 213.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 274 |
| Maintainers | thesonofthomp, shaneeza, stephl3, aitchpgm, hnevins, _tsck |

## Links

- npm: https://www.npmjs.com/package/@leafygreen-ui/checkbox
- Repository: https://github.com/mongodb/leafygreen-ui
- Homepage: https://github.com/mongodb/leafygreen-ui/tree/main/packages/checkbox
- Issues: https://jira.mongodb.org/projects/PD/summary
- npm.io page: https://npm.io/package/@leafygreen-ui/checkbox

## Dependencies (9)

- [@leafygreen-ui/lib](https://npm.io/package/@leafygreen-ui/lib.md) ^15.7.1
- [@leafygreen-ui/a11y](https://npm.io/package/@leafygreen-ui/a11y.md) ^3.0.6
- [@leafygreen-ui/hooks](https://npm.io/package/@leafygreen-ui/hooks.md) ^9.3.2
- [@leafygreen-ui/tokens](https://npm.io/package/@leafygreen-ui/tokens.md) ^4.2.3
- [@leafygreen-ui/emotion](https://npm.io/package/@leafygreen-ui/emotion.md) ^5.2.1
- [@leafygreen-ui/palette](https://npm.io/package/@leafygreen-ui/palette.md) ^5.0.3
- [react-transition-group](https://npm.io/package/react-transition-group.md) ^4.4.5
- [@lg-tools/test-harnesses](https://npm.io/package/@lg-tools/test-harnesses.md) ^0.3.5
- [@leafygreen-ui/typography](https://npm.io/package/@leafygreen-ui/typography.md) ^22.2.5

## Recent versions

- 18.1.6 (latest) — 2026-10-02
- 12.0.13 (beta) — 2023-07-26
- 13.0.0-alpha.1 (alpha) — 2023-07-20
- 12.0.11-next.7 (next) — 2023-05-26
- 10.1.0-test.0 (test) — 2022-09-22
- 18.1.5 — 2026-01-21
- 18.1.4 — 2025-11-24
- 18.1.3 — 2025-11-13
- 18.1.2 — 2025-10-31
- 18.1.1 — 2025-10-21
- 18.1.0 — 2025-10-07
- 18.0.4 — 2025-09-25
- 18.0.3 — 2025-09-10
- 18.0.2 — 2025-09-03
- 18.0.1 — 2025-07-03
- … 102 more at https://npm.io/package/@leafygreen-ui/checkbox/versions

## README

# Checkbox

![npm (scoped)](https://img.shields.io/npm/v/@leafygreen-ui/checkbox.svg)

#### [View on MongoDB.design](https://www.mongodb.design/component/checkbox/live-example)

## Installation

### PNPM

```shell
pnpm add @leafygreen-ui/checkbox
```

### Yarn

```shell
yarn add @leafygreen-ui/checkbox
```

### NPM

```shell
npm install @leafygreen-ui/checkbox
```

## Example

```js
import Checkbox from '@leafygreen-ui/checkbox';

<Checkbox
  className="my-checkbox"
  onChange={event => {
    /* Something to handle the click event */
  }}
  label="This is how you enable a thing"
  checked={true}
  bold={false}
/>;
```

## Properties

| Prop              | Type                      | Description                                                                                                                                                                                                                  | Default                   |
| ----------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `darkMode`        | `boolean`                 | Determines whether or not the Checkbox will appear in dark mode.                                                                                                                                                             | `false`                   |
| `checked`         | `boolean`                 | Checks the checkbox                                                                                                                                                                                                          | `false`                   |
| `label`           | `node`                    | The label for the checkbox.                                                                                                                                                                                                  | `''`                      |
| `description`     | `string`                  | A description for the checkbox.                                                                                                                                                                                              | `''`                      |
| `disabled`        | `boolean`                 | Disables the checkbox.                                                                                                                                                                                                       | `false`                   |
| `indeterminate`   | `boolean`                 | Sets the checkbox as indeterminate. **NOTE:** the checkbox will become out of sync with the indeterminate prop when it's clicked. Make sure to unset the `indeterminate` prop on change where you're controlling your input. | `false`                   |
| `className`       | `string`                  | Adds a className to the outermost element.                                                                                                                                                                                   | `''`                      |
| `animate`         | `boolean`                 | Determines whether the checkbox will be animated when checked or unchecked. Note the "ripple" animation will only run when `Checkbox` is rendered within `LeafygreenProvider`, and only on click.                            | `true`                    |
| `id`              | `string` or `number`      | Adds an ID only to the input, and it's used elsewhere for accessibility props.                                                                                                                                               | randomly generated string |
| `onChange`        | `function`                | The event handler function for the `onChange` event. Receives the associated `event` object as the first argument.                                                                                                           | `() => {}`                |
| `bold`            | `boolean`                 | Determines whether the text will be bold or not. (Currently disregarded in the new design)                                                                                                                                   | `false`                   |
| `aria-labelledby` | `string`                  | A value for `aria-labelledby`. Allows use of the component with an external `<label>` element                                                                                                                                |                           |
| `aria-label`      | `string`                  | A value for `aria-label`. Allows use of the component without a `label`                                                                                                                                                      |                           |
| ...               | native `input` attributes | Any other props will be spread on the root `input` element                                                                                                                                                                   |                           |

_Any other properties will be spread on the `input` element._

# Test Harnesses

## getTestUtils()

`getTestUtils()` is a util that allows consumers to reliably interact with `LG Checkbox` in a product test suite. If the `Checkbox` component cannot be found, an error will be thrown.

### Usage

```tsx
import Checkbox, { getTestUtils } from '@leafygreen-ui/checkbox';

const utils = getTestUtils(lgId?: string); // lgId refers to the custom `data-lgid` attribute passed to `Checkbox`. It defaults to 'lg-checkbox' if left empty.
```

#### Single `Checkbox`

```tsx
import { render } from '@testing-library/react';
import Checkbox, { getTestUtils } from '@leafygreen-ui/checkbox';

...

test('checkbox', () => {
  render(<Checkbox label="label" checked />);
  const { getInput, getInputValue } = getTestUtils();

  expect(getInput()).toBeInTheDocument();
  expect(getInputValue()).toBe(true);
});
```

#### Multiple `Checkbox` components

When testing multiple `Checkbox` components it is recommended to add the custom `data-lgid` attribute to each `Checkbox`.

```tsx
import { render } from '@testing-library/react';
import Checkbox, { getTestUtils } from '@leafygreen-ui/checkbox';

...

test('checkbox', () => {
  render(
    <>
      <Checkbox data-lgid="checkbox-1" label="label 1" />
      <Checkbox data-lgid="checkbox-2" label="label 2" checked />
    </>,
  );
  const utilsOne = getTestUtils('checkbox-1'); // data-lgid
  const utilsTwo = getTestUtils('checkbox-2'); // data-lgid
  // First Checkbox
  expect(utilsOne.checkboxetInput()).toBeInTheDocument();
  expect(utilsOne.getInputValue()).toBe(false);

  // Second Checkbox
  expect(utilsTwo.getInput()).toBeInTheDocument();
  expect(utilsTwo.getInputValue()).toBe(true);
});
```

#### Checkbox with other LG form elements

```tsx
import { render } from '@testing-library/react';
import Toggle, { getTestUtils as getLGToggleTestUtils } from '@leafygreen-ui/toggle';
import TextInput, { getTestUtils as getLGTextInputTestUtils } from '@leafygreen-ui/text-input';
import Checkbox, { getTestUtils } from '@leafygreen-ui/checkbox';

...

test('Form', () => {
  render(
    <Form>
      <Toggle aria-label="Toggle label" />
      <TextInput label="TextInput label" />
      <Checkbox label="Checkbox label" />
    </Form>,
  );

  const toggleInputUtils = getLGToggleTestUtils();
  const textInputUtils = getLGTextInputTestUtils();
  const checkboxUtils = getTestUtils();

  // LG Toggle
  expect(toggleInputUtils.getInput()).toBeInTheDocument();
  expect(toggleInputUtils.getInputValue()).toBe('false');

  // LG TextInput
  expect(textInputUtils.getInput()).toBeInTheDocument();
  expect(textInputUtils.getInputValue()).toBe('');

  // LG Checkbox
  expect(checkboxUtils.getInput()).toBeInTheDocument();
  expect(checkboxUtils.getInputValue()).toBe(false);
});
```

### Test Utils

#### Elements

```tsx
const {
  getInput,
  getLabel,
  getDescription,
  getInputValue,
  isDisabled,
  isIndeterminate,
} = getTestUtils();
```

| Util              | Description                                | Returns                       |
| ----------------- | ------------------------------------------ | ----------------------------- |
| `getInput`        | Returns the input node                     | `HTMLButtonElement`           |
| `getLabel`        | Returns the label node                     | `HTMLButtonElement` \| `null` |
| `getDescription`  | Returns the description node               | `HTMLButtonElement` \| `null` |
| `getInputValue`   | Returns the input value                    | `boolean`                     |
| `isDisabled`      | Returns whether the input is disabled      | `boolean`                     |
| `isIndeterminate` | Returns whether the input is indeterminate | `boolean`                     |

---
_Source: https://npm.io/package/@leafygreen-ui/checkbox · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._