Skip to main content

Switch

A switch is an interactive element that allows users to switch between two states or options with a single action.

Overview

GitHub Workflow Status GitHub Workflow Status

pie-switch is a Web Component built using Lit. It offers a simple and accessible switch component for web applications.

This component can be easily integrated into various frontend frameworks and customised through a set of properties.

Installation

To install pie-switch in your application, run the following on your command line:

npm i @justeattakeaway/pie-webc
yarn add @justeattakeaway/pie-webc

Props

PropOptionsDescriptionDefault
checkedtrue
false
Same as the HTML checked attribute; indicates whether the switch is on or off.false
disabledtrue
false
Same as the HTML disabled attribute; indicates whether the switch is disabled or not.false
requiredtrue
false
Same as the HTML required attribute; indicates whether the switch must be turned on when submitted as part of a form.false
labelThe label text for the switch.
labelPlacement"leading"
"trailing"
Set the placement of the label. Leading will have the label before the switch, taking writing direction into account."leading"
aria{ label?: string, describedBy?: string }
The ARIA labels used for the switch.undefined
nameIndicates the name of the switch (for use with forms).
valueIndicates the value of the switch (for use with forms).on

Events

This component emits the change event when toggled. This allows you to treat it like a native checkbox (<input type="checkbox" />) element when listening for events.

For examples of how to add an event listener, see the Examples section below.

Examples

HTML and native JS

main.js

Register the component in JavaScript:

import '@justeattakeaway/pie-webc/components/switch.js';

index.html

Then, having imported main.js into your HTML file, you can use the component:

<pie-switch id="switch" checked label="Label" labelPlacement="trailing"></pie-switch>

<script>
document.querySelector('#switch').addEventListener('change', (event) => {
    console.log(event.target.checked);
});
</script>

or, instead of using a script tag, you can use an event attribute (note the on prefix):

<pie-switch
  label="Label"
  onchange="(event) => {
    console.log(event.target.checked);
  }">
</pie-switch>

Vue, Angular, Svelte, etc.

The general approach is similar here: import the component (to register it in the browser as a custom element) then use it in an HTML template.

Note that as the component has already been registered in the browser, you don't need to declare the web component like you would when importing a component written in your chosen framework; i.e. you can treat it like a native HTML element.

<script>
  import '@justeattakeaway/pie-webc/components/switch.js';
</script>

<template>
  <pie-switch checked label="Label" labelPlacement="trailing" @change="handleChange"></pie-switch>
</template>

React

import { PieSwitch } from '@justeattakeaway/pie-webc/react/switch.js';

<PieSwitch checked label="Label" labelPlacement="trailing" onChange={handleChange}></PieSwitch>
// React templates (using Next 13 and SSR)
import { PieSwitch } from '@justeattakeaway/pie-switch/dist/react';

<PieSwitch checked label="Label" labelPlacement="trailing" onChange={handleChange}></PieSwitch>

Form integration

The pie-switch component can be integrated into HTML forms similarly to native HTML input elements. The component will associate itself with any form it is placed inside. As long as you provide a name attribute, the component will be included in the form's submission payload. A value attribute can also be provided, but if not then it will have a default value of on.

<form action="/default-endpoint" method="POST">
  <pie-switch name="switch" value="someValue" label="Click me"></pie-switch>
  <button type="submit">Submit</button>
</form>

Form Validation

To make pie-switch a required form field, simply add the required attribute to the component markup. This will prevent the form from being submitted if the switch is not toggled and will trigger native HTML form validation.

Currently this defaults to browser styling, but this may be updated in the future.

<form action="/default-endpoint" method="POST">
  <pie-switch name="switch" value="someValue" label="Click me" required></pie-switch>
  <button type="submit">Submit</button>
</form>

To set a custom validation message, please call the setCustomValidity method exposed by the component. This will allow you to set a custom message that will be displayed when the form is submitted without the switch being toggled.

This behaviour is consistent with native HTML input elements. We may revisit this to provide a prop to set the custom validation message in the future.

const switch = document.querySelector('pie-switch');
switch.setCustomValidity('Please toggle the switch');

Changelog