@justeattakeaway/pie-switch

Source Code | Design Documentation | NPM

@justeattakeaway/pie-switch is a Web Component built using the Lit library. It offers a simple and accessible interactive switch component for web applications.

Table of Contents

• Installation
• Documentation
  • Properties
  • Slots
  • CSS Variables
  • Events
• Forms Usage
  • Form Validation
• External Labels
• Usage Examples
• Questions and Support
• Contributing

Installation

To install any of our web components in your application, we would suggest following the getting started guide to set up your project.

Ideally, you should install the component using the @justeattakeaway/pie-webc package, which includes all of the components. Or you can install the individual component package.

Documentation

Properties

| Prop | Options | Description | Default | |------------------|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|-------------| | checked | true, false | Same as the HTML checked attribute; indicates whether the switch is on or off. | false | | defaultChecked | true, false | Sets the default checked state for the switch. This does not directly set the initial checked state when the page loads, use checked for that. If the switch is inside a form which is reset, the checked state will be updated to match defaultChecked. | 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" |

Slots

This component does not have any slots. All content is passed through properties.

CSS Variables

This component does not expose any CSS variables for style overrides.

Events

This component does not emit any custom events. In order to add event listening to this component, you can treat it like a native HTML element in your application.

Forms Usage

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

External Labels

In addition to the built-in label property, pie-switch can be associated with one or more external <label> elements: either by for="…" referencing the switch's id, or by wrapping the switch in a <label>. Clicking any associated label toggles the switch, mirroring native <input type="checkbox"> behaviour. The labels will be narrated by screen readers. Do not use the label property when associating the switch with external labels.

Warning! Be mindful of using the aria object property when associating with external labels as it could cause a messy screen reader narration. Always test your switches with screen readers.

Using for="…":

<label for="notifications">Enable notifications</label>
<pie-switch id="notifications" name="notifications"></pie-switch>

Using a wrapping label:

<label>
  Enable notifications
  <pie-switch name="notifications"></pie-switch>
</label>

Multiple labels for the same switch (not a very common pattern):

<label for="notifications">Enable notifications</label>
<pie-switch id="notifications" name="notifications"></pie-switch>
<label for="notifications">(tap to toggle)</label>

Each associated label will toggle the switch when clicked, and is announced by screen readers.

Usage Examples

For HTML:

// import as module into a js file e.g. main.js
import '@justeattakeaway/pie-webc/components/card.js';

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

<script type="module" src="/main.js"></script>

For Native JS Applications, Vue, Angular, Svelte etc.:

// Vue templates (using Nuxt 3)
import '@justeattakeaway/pie-webc/components/switch.js';

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

For React Applications:

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

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

Questions and Support

If you work at Just Eat Takeaway.com, please contact us on #help-designsystem. Otherwise, please raise an issue on Github.

Contributing

Check out our contributing guide for more information on local development and how to run specific component tests.