Switch

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

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