Checkbox

A checkbox is an interactive element that allows users to select or deselect an option.

Overview

pie-checkbox is a Web Component built using Lit.

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

Installation

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

npm i @justeattakeaway/pie-webc

yarn add @justeattakeaway/pie-webc

Peer Dependencies

When using pie-checkbox, you will also need to include a couple of dependencies to ensure the component renders as expected. See the PIE Wiki for more information and how to include these in your application.

Props

Prop	Options	Type	Description	Default
name	`-`	`String`	The name of the checkbox (used as a key/value pair with `value`). This is required in order to work properly with forms.	`-`
value	`-`	`String`	The value of the input (used as a key/value pair in HTML forms with name). If not passed falls back to the html default value "on".	`"on"`
required	`-`	`Boolean`	If true, the checkbox is required to be checked before submitting the form. If it is not in checked state, the component validity state will be invalid.	`false`
disabled	`-`	`Boolean`	Indicates whether or not the checkbox is disabled.	`false`
checked	`-`	`Boolean`	Controls whether or not the checkbox is checked.	`false`
defaultChecked	`-`	`Boolean`	Sets the default checked state for the checkbox. This does not directly set the initial checked state when the page loads, use `checked` for that. If the checkbox is inside a form which is reset, the `checked` state will be updated to match `defaultChecked`.	`false`
indeterminate	`-`	`Boolean`	Indicates whether the checkbox visually shows a horizontal line in the box instead of a check/tick. It has no impact on whether the checkbox's value is used in a form submission. That is decided by the checked state, regardless of the indeterminate state.	`false`
assistiveText	`-`	`String`	Allows assistive text to be displayed below the checkbox element.	`-`
status	`"default"` `"error"` `"success"`	`String`	The status of the checkbox component / assistive text. If you use `status` you must provide an `assistiveText` prop value for accessibility purposes.	`"default"`

Slots

Slot	Description
`default`	The default, unnamed slot is used to pass in text to the component.

Events

Event	Type	Description
`change`	`CustomEvent`	Triggered after the checked state of a checkbox changes.

Importing and usage in templates

For Native JS Applications:

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

<!-- pass js file into <script> tag -->
<pie-checkbox name="mycheckbox">Label</pie-checkbox>
<script type="module" src="/main.js"></script>

For Vue Applications:

// import as module into a js file that will be loaded on the page where the component is used.
import '@justeattakeaway/pie-webc/components/checkbox.js';

<pie-checkbox name="mycheckbox">Label</pie-checkbox>

For React Applications:

import { PieCheckbox } from '@justeattakeaway/pie-webc/react/checkbox.js';

<PieCheckbox name="mycheckbox">Label</PieCheckbox>

// React templates (using Next 13 and SSR)
import { PieCheckbox } from '@justeattakeaway/pie-checkbox/dist/react';

<PieCheckbox name="mycheckbox">Label</PieCheckbox>

Examples with and without a label:

<!-- Native HTML -->
<pie-checkbox name="mycheckbox">Label</pie-checkbox>

<!-- Without a label it is necessary to pass aria-label or aria-labelledby attributes to the component  -->
<pie-checkbox name="mycheckbox" aria-label="Label"></pie-checkbox>

<!-- JSX -->
<PieCheckbox name="mycheckbox">Label</PieCheckbox>
<PieCheckbox name="mycheckbox" aria-label="Label"></PieCheckbox>

Validation

The checkbox component utilizes the constraint validation API to provide a queryable validity state for consumers. This means that the component's validity can be checked via a validity getter.

Example:

const checkbox = document.querySelector('pie-checkbox');
console.log(checkbox.validity.valid);

This getter can be useful for reducing the amount of validation code in your application. For example, if you want to create a checkbox that requires attention, you can set the required property on the component. You can then check the validity of the input in your application code:

<pie-checkbox
  id="my-checkbox"
  required></pie-checkbox>

const checkbox = document.querySelector('pie-checkbox');
const isValid = checkbox.validity.valid;

// We could use this to drive the status and assistiveText properties on our checkbox (this would likely be inside a submit event handler in a real application)
if (!isValid) {
  checkbox.status = 'error';
  checkbox.assistiveText = 'This checkbox is required';
}

These concepts work just as well inside a Vue or React application.