npm package: @highlight-ui/checkbox
Description: Checkbox for Highlight UI
Author: Personio GmbH & Co. KG
Latest version: 5.1.15

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

# @highlight-ui/checkbox

A control that allows the user to toggle between checked and unchecked states. Used when there are multiple items available to select, where users can pick zero, one or many items. If you require a single-selection input, please use the [RadioButton](https://www.npmjs.com/package/@highlight-ui/radio-button).

## Features

- Checkbox
  - Controlled component
  - Toggle to disable
  - Optional label to display next to the checkbox input
  - Optional sub-label to display under the main label
  - Optional tooltip placed next to the main input label
- Checkbox group
  - Renders multiple checkboxes given array of options
  - Controlled component
  - Vertical or horizontal display
  - Toggle to disable all checkboxes within the group
  - Optional name to apply to all checkboxes within the group

## Installation

Using npm:

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

Using yarn:

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

Using pnpm:

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

In your (S)CSS file:

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

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

```tsx
import { Checkbox, CheckboxGroup } from '@highlight-ui/checkbox';
```

## Usage

### Checkbox

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

export default function CheckboxExample() {
  const [checkedStatus, setCheckedStatus] = useState(false);

  return (
    <Checkbox
      id="checkbox"
      label="Click me to tick me"
      subLabel="I am only a checkbox input"
      checked={checkedStatus}
      onClick={() => setCheckedStatus(!checkedStatus)}
    />
  );
}
```

### Checkbox group

```tsx
import React from 'react';
import { CheckboxGroup } from '@highlight-ui/checkbox';

export default function CheckboxGroupExample() {
  const [value, setValue] = useState<string[]>([]);
  const options = [
    { value: 'option-a', label: 'Option A', subLabel: 'Most important' },
    { value: 'option-b', label: 'Option B', subLabel: 'Average' },
    { value: 'option-c', label: 'Option C', subLabel: 'Lowest priority' },
  ];

  return (
    <CheckboxGroup
      name="checkbox-group"
      orientation="horizontal"
      options={options}
      value={value}
      onChange={(selectedOptions) => {
        const values = selectedOptions.map((v) => v.value) as string[];
        setValue(values);
      }}
    />
  );
}
```

## Props 📜

### Checkbox

> All `HTMLInputElement` and [PropsWithMetadata(https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/utils/commons/src/types.ts#L24)] props are accepted with this component. In addition to these, this component has the following props

| Prop                   | Type                                        | Required | Default   | Description                                                                                                                                                                                                                                                                     |
| :--------------------- | :------------------------------------------ | :------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label`                | `string`                                    | No       | `null`    | Text displayed next to the checkbox input                                                                                                                                                                                                                                       |
| `subLabel`             | `string`                                    | No       | `null`    | Text displayed below the main label                                                                                                                                                                                                                                             |
| `tooltipContent`       | `React.ReactNode`                           | No       | `null`    | The content of the tooltip pop-out. When supplied, a tooltip will be placed next to the label. This maps to the [TooltipProps['content']](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/tooltip/src/Tooltip.tsx#L21) prop types. |
| `tooltipMouseOutDelay` | `'none'`, `'medium'`, `'long'`, or `number` | No       | `null`    | Specifies how to to keep the tooltip opened after the mouse has left the tooltip icon. This maps to the [TooltipProps['mouseOutDelay']](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/tooltip/src/Tooltip.tsx#L14) prop types.   |
| `tone`                 | `default` or `error`                        | No       | `default` | Sets the tone of the checkbox                                                                                                                                                                                                                                                   |
| `indeterminate`        | `boolean`                                   | No       | `null`    | Sets the partial state of the checkbox                                                                                                                                                                                                                                          |

### CheckboxGroup

Note that the `CheckboxGroupOption` type matches the `Checkbox` listed properties above.

| Prop          | Type                                            | Required | Default    | Description                                                  |
| :------------ | :---------------------------------------------- | :------- | :--------- | :----------------------------------------------------------- |
| `value`       | `CheckboxGroupOption['value'][]`                | Yes      |            | Currently checked values                                     |
| `onChange`    | `function(option: CheckboxGroupOption[]): void` | Yes      |            | Function called when the checked status of an option changes |
| `orientation` | `vertical` or `horizontal`                      | No       | `vertical` | Display of the checkboxes group                              |
| `options`     | `CheckboxGroupOption[]`                         | Yes      |            | Options to render as a group                                 |

## Accessibility ♿️

Following [base accesibility guidelines](https://www.magentaa11y.com/checklist-web/checkbox/), the checkbox input currently:

- Allows clicking checkbox input and main label to check or uncheck
- Associates the checkbox input with its label through the `for` prop referring to the `id`

Potential future improvements to make it more accessible:

- Adding focus on the whole checkbox and label container
- Including `aria` tags to indicate checked and disabled states
- Tooltip accessibility will be addressed in a future release as it is currently not adequate

## Testing

There are a number of unit tests covering the `Checkbox` and `CheckboxGroup` components, 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.

### Checkbox

```tsx
import React from 'react';
import { render } from '@testing-library/react';

import { Checkbox, CheckboxProps } from '@highlight-ui/checkbox';

type Optional<T, K extends keyof T> = Omit<T, K> & Partial<T>;
type CheckboxWrapperProps = Optional<CheckboxProps, 'checked' | 'onClick'>;

function CheckboxWrapper(props: CheckboxWrapperProps) {
  const [checkedStatus, setCheckedStatus] = useState(false);

  return (
    <Checkbox
      checked={checkedStatus}
      onClick={() => setCheckedStatus(!checkedStatus)}
      {...props}
    />
  );
}

describe('CheckboxTest', () => {
  const renderCheckboxWrapper = (props: CheckboxWrapperProps) => {
    return render(<CheckboxWrapper {...props} />);
  };

  it('test description', () => {
    renderCheckboxWrapper({});
    // write your expect here
  });
});
```

### CheckboxGroup

```tsx
import React from 'react';
import { render } from '@testing-library/react';

import { CheckboxGroup, CheckboxGroupProps, CheckboxGroupOption } from '@highlight-ui/checkbox';

type Optional<T, K extends keyof T> = Omit<T, K> & Partial<T>;
type CheckboxGroupWrapperProps = Optional<
  CheckboxGroupProps<CheckboxGroupOption>,
  'options' | 'value' | 'onChange'
>;

function CheckboxGroupWrapper(props: CheckboxGroupWrapperProps) {
   const [value, setValue] = useState<string[]>([]);

  const options = [
    {
      value: 'earth-day',
      label: 'Earth day',
      subLabel: 'Demonstrate support for environmental protection',
    },
    {
      value: 'water-day',
      label: 'World Water Day',
      subLabel: 'Highlights the importance of fresh water',
    }
  ];

  return (
    <CheckboxGroup
      options={options}
      value={value}
      onChange={(selectedOptions) => {
        const values = selectedOptions.map((v) => v.value) as string[];
        setValue(values);
      }}
      {...props}
    />
  );
}

describe('CheckboxGroupTest', () => {
  const renderCheckboxGroupWrapper = (props: CheckboxGroupWrapperProps) => {
    return render(<CheckboxWrapper {...props} />);
  };

  it('test description', () => {
    renderCheckboxGroupWrapper({});
    // write your expect here
  });
};
```

## Place in design system 💻

The checkbox is used across our library, when there is the existence of multiple choices or bulk selection is available.

Used as part of other components, such as:

- [accordion](https://www.npmjs.com/package/@highlight-ui/accordion)
- [file-management](https://www.npmjs.com/package/@highlight-ui/file-management)
- [select](https://www.npmjs.com/package/@highlight-ui/select)

When there are mutually exclusive choices or functionalities need to be toggled, please use alternative components:

- [radio-button](https://www.npmjs.com/package/@highlight-ui/radio-button)
- [toggle](https://www.npmjs.com/package/@highlight-ui/toggle)

## Contributing 🖌️

Please visit [personio.design](https://www.personio.design/40d648a47/v/0/p/7195bd-checkbox) 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).