npm package: @highlight-ui/toggle
Description: Toggle component for Highlight UI library
Author: Personio GmbH & Co. KG
Latest version: 1.3.3

[![npm](https://img.shields.io/npm/v/@highlight-ui/toggle)](https://www.npmjs.com/package/@highlight-ui/toggle)
[![personio.design](https://img.shields.io/static/v1?label=Personio&message=zeroheight&color=yellow)](https://www.personio.design/40d648a47/v/0/p/11ba3a-toggle/b/983c46)
[![storybook.personio.design](https://img.shields.io/static/v1?label=Personio&message=storybook&color=red)](https://storybook.personio.design/?path=/story/forms-and-input-toggle)

# @highlight-ui/toggle

A two-state switch which allows turning a certain option on or off.

## Features

- Controlled component
- Ability to disable via prop
- Supports customization through CSS classes
- Optional title and subtitle to render on the left hand side of the component

## Installation

Using npm:

```bash
npm install @highlight-ui/toggle
```

Using yarn

```bash
yarn add @highlight-ui/toggle
```

Using pnpm:

```bash
pnpm install @highlight-ui/toggle
```

In your (S)CSS file:

```scss
@import url('@highlight-ui/toggle');
```

Once the package is installed, you can import the library:

```ts
import { Toggle } from '@highlight-ui/toggle';
```

## Usage

```tsx
import React, { useState } from 'react';
import { Toggle } from '@highlight-ui/toggle';

export default function ToggleExample() {
    const [toggleStatus, setToggleStatus] = useState(false);

    return (
        <Toggle
            title="I am the title"
            subTitle="I am the subtitle"
            checked={toggleStatus}
            onToggle={() => setToggleStatus(!toggleStatus)}
        />
    );
}
```

## Advanced usage

### Customizing through a CSS class name

Use the `className` prop to customize the component through CSS classes.

```tsx
import React, { useState } from 'react';
import { Toggle } from '@highlight-ui/toggle';
import styles from './customStyles.scss';

export default function CustomisedToggleExample() {
  const [toggleStatus, setToggleStatus] = useState(false);

  return (
        <Toggle 
            className={styles.wrappedText} 
            checked={toggleStatus}
            onToggle={() => setToggleStatus(!toggleStatus)}
        />
    );
}
```

## Props 📜

To ensure that the toggle input is [consistently controlled through its lifecycle](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable), an initial `checked` value and `onToggle` callback must be provided.


| Prop             | Type                            | Required | Default       | Description                                                                 |
| :--------------- | :------------------------------ | :------- | :------------ | :-------------------------------------------------------------------------- |
| `checked`        | `boolean`                       | Yes      |               | Whether the toggle is on or off.                                             |
| `onToggle`       | `function(e: MouseEvent): void` | Yes      |               | Function called when the toggle input is clicked on.                         |
| `className`      | `string`                        | No       | `undefined`    | Allows providing a custom class name                                        |
| `disabled`       | `boolean`                       | No       | `false`       | Whether the toggle is disabled                                              |
| `id`             | `string`                        | No       | `undefined`    | ID to apply to the toggle input                                             |
| `title`          | `string`                        | No       | `undefined`    | Text displayed next to the toggle input. Must be used alongside `subTitle`. |
| `subTitle`       | `string`                        | No       | `undefined`    | Text displayed next to the toggle input. Must be used alongside `title`.    |


## Accessibility ♿️

At the time of writing, it follows the same base accesibility guidelines as the [@highlight-ui/checkbox component](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/tree/master/packages/ui/checkbox#accessibility-%EF%B8%8F).

## Testing

There are a number of unit tests covering the `Toggle`, where the snippets below can serve as a base to expand future testing if new behaviours are added.

The relevant render methods provide the option to add or override prop values.


```tsx
import React from 'react';
import { render } from '@testing-library/react';
import { Toggle, ToggleProps } from '@highlight-ui/toggle';

function renderToggle(props: ToggleProps) {
    render(<Toggle {...props} />);
}

describe('ToggleTest', () => {
    it('toggle test description', () => {
        const onToggle = jest.fn();
        renderToggle({ checked: true, onToggle });
        // write your expect here
    });
});
```

## Place in design system 💻

When there are mutually exclusive choices or functionalities that need to be toggled, it can also be interchanged with the [radio button](https://www.npmjs.com/package/@highlight-ui/radio-button).


## Contributing 🖌️

Please visit [personio.design](https://www.personio.design/40d648a47/v/0/p/11ba3a-toggle/b/983c46) for usage guidelines and visual examples.

If you're interested in contributing, please visit our [contribution page](https://www.personio.design/40d648a47/v/0/p/138faf-about-the-process).