@highlight-ui/toggle NPM

@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
    });
});