@leafygreen-ui/checkbox
TypeScript icon, indicating that this package has built-in type declarations

13.1.2 • Public • Published

Checkbox

npm (scoped)

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

Readme

Keywords

none

Package Sidebar

Install

npm i @leafygreen-ui/checkbox

Weekly Downloads

28,590

Version

13.1.2

License

Apache-2.0

Unpacked Size

259 kB

Total Files

66

Last publish

Collaborators

  • stephl3
  • brookescarlett
  • shaneeza
  • hswolff
  • thesonofthomp