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

npm install @highlight-ui/toggle

Using yarn

yarn add @highlight-ui/toggle

Using pnpm:

pnpm install @highlight-ui/toggle

In your (S)CSS file:

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

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

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

Usage

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.

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

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.

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.

Contributing 🖌️

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

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