@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.

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:

npm install @highlight-ui/checkbox

Using yarn:

yarn add @highlight-ui/checkbox

Using pnpm:

pnpm install @highlight-ui/checkbox

In your (S)CSS file:

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

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

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

Usage

Checkbox

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

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'] 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'] 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, 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

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

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
• file-management
• select

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

• radio-button
• toggle

Contributing 🖌️

Please visit personio.design for usage guidelines and visual examples.

If you're interested in contributing, please visit our contribution page.