Switch

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

Overview

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

Prop	Options	Description	Default
checked	`true` `false`	Same as the HTML `checked` attribute; indicates whether the switch is on or off.	`false`
disabled	`true` `false`	Same as the HTML `disabled` attribute; indicates whether the switch is disabled or not.	`false`
required	`true` `false`	Same as the HTML `required` attribute; indicates whether the switch must be turned on when submitted as part of a form.	`false`
label		The 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`
name		Indicates the name of the switch (for use with forms).
value		Indicates 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

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>

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');