@highlight-ui/toggle
TypeScript icon, indicating that this package has built-in type declarations

1.3.3 • Public • Published

npm personio.design storybook.personio.design

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

Readme

Keywords

none

Package Sidebar

Install

npm i @highlight-ui/toggle

Weekly Downloads

8

Version

1.3.3

License

MIT

Unpacked Size

66 kB

Total Files

13

Last publish

Collaborators

  • riain-personio
  • yunxi-yang
  • andresfrompersonio
  • kbpersonio
  • jordan-personio
  • amadeofrompersonio
  • cusero
  • mislav_lukac_personio_ext
  • ante.zebic
  • personio-npm-ci