Toggle

!npm (scoped)

#### View on MongoDB.design

Installation

$3

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

$3

`shell
yarn add @leafygreen-ui/toggle
`

$3

`shell
npm install @leafygreen-ui/toggle
`

Example

`js
import Toggle from '@leafygreen-ui/toggle';

return (
<>

Change setting


id="toggle"
aria-labelledby="label"
onChange={(checked, event) => {
/ Handle the change event /
}}
/>

);
`

Properties

| Prop | Type | Description | Default |
| ----------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| darkMode | boolean | Determines if the Toggle will render the dark mode styles. | false |
| size | 'default', 'small', 'xsmall' | Sets the size of the toggle. | 'default' |
| checked | boolean | Set's the checked state of the Toggle. | |
| disabled | boolean | Disables the Toggle. | false |
| onChange | (checked, MouseEvent) => void | onChange fires when the checked state of the component is being updated. Receives the updated checked state of the toggle as its first argument, and the associated mouse event as the second. | |
| className | string | Adds a className to the outermost element. | '' |
| ... | HTML button attributes | Any supported HTML button properties will be applied to the button element. | |

Accessibility

For the Toggle to be accessible to screen readers, you must pass either aria-label or aria-labelledby to Toggle. Please note, if this is a part of a form, this is in addition to using htmlFor to associate a label with the Toggle. You will see TypeScript and console errors if this isn't done.

Please reach out if you would like further guidance on how to programmatically associate text with the Toggle component.

Test Harnesses

getTestUtils()

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

$3

`tsx
import Toggle, { getTestUtils } from '@leafygreen-ui/toggle';

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

#### Single Toggle

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

...

test('toggle', () => {
render();
const { getInput, getInputValue } = getTestUtils();

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

#### Multiple Toggle's

When testing multiple Toggle's it is recommended to add the custom data-lgid attribute to each Toggle.

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

...

test('toggle', () => {
render(
<>


,
);
const utilsOne = getTestUtils('toggle-1'); // data-lgid
const utilsTwo = getTestUtils('toggle-2'); // data-lgid

// First toggle
expect(utilsOne.getInput()).toBeInTheDocument();
expect(utilsOne.getInputValue()).toBe(false);

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

#### Toggle with other LG form elements

`tsx
import { render } from '@testing-library/react';
import Toggle, { getTestUtils as getToggleTestUtils } from '@leafygreen-ui/toggle';
import TextInput, { getTestUtils as getTextInputTestUtils } from '@leafygreen-ui/text-input';
import TextArea, { getTestUtils as getTextAreaTestUtils } from '@leafygreen-ui/text-area';

...

test('Form', () => {
render(