Checkbox
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);
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');
const utilsTwo = getTestUtils('checkbox-2');
expect(utilsOne.checkboxetInput()).toBeInTheDocument();
expect(utilsOne.getInputValue()).toBe(false);
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();
expect(toggleInputUtils.getInput()).toBeInTheDocument();
expect(toggleInputUtils.getInputValue()).toBe('false');
expect(textInputUtils.getInput()).toBeInTheDocument();
expect(textInputUtils.getInputValue()).toBe('');
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 |