@highlight-ui/checkbox v5.1.7

@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

CheckboxGroup

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

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.