checkbox

Checkbox

View on MongoDB.design

Installation

Yarn

yarn add @leafygreen-ui/checkbox

NPM

npm install @leafygreen-ui/checkbox

Example

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}
/>;

Output HTML

<label
  class="css-1rgbgdt my-checkbox"
  title="Create an item"
  for="checkbox-14827892"
>
  <input
    checked
    type="checkbox"
    role="checkbox"
    class="css-32kjhsdaf"
    id="checkbox-14827892"
    name="checkbox-14827892"
    aria-disabled="false"
    aria-checked="true"
    aria-labeledby="checkbox-14827892-label"
  />

  <div class="css-34kjkdfg">
    <div class="css-98sdfjsad"></div>
  </div>

  <span class="css-8xdsjfh9" id="checkbox-14827892-label">
    This is how you enable a thing
  </span>
</label>

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

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

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.

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

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

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