Select Input

A select input presents users with a list of options within a form, allowing them to choose a single item from the list.

Overview

pie-select is a Web Component built with Lit, providing a simple and accessible select input for web applications. It allows users to choose a single option from a predefined list.

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

Installation

To install pie-select in your application via npm or yarn:

npm i @justeattakeaway/pie-webc

yarn add @justeattakeaway/pie-webc

Props

Prop	Options	Description	Default
size	`"small"` `"medium"` `"large"`	The size of the select component.	`medium`
disabled	`boolean`	Whether the select is disabled.	`false`
assistiveText	`string`	An optional assistive text to display below the select element. Must be provided when the status is error.	`undefined`
status	`"default"` `"error"`	The status of the select component / assistive text.	`default`
name	`string`	The name of the select (used as a key/value pair with `value`). This is required in order to work properly with forms.	`undefined`
options	`array`	The options to display in the select. Can be an array of option objects or option group objects. See Using the options prop for more details.	`[]`

Using the `options` prop

The options prop accepts an array of option objects or option group objects:

Option objects

Prop	Options	Description	Default
tag	`"option"`	Must be `option` to identify this as an option.	`undefined`
text	`string`	The text to display for the option.	`undefined`
value	`string`	The value for the option.	`undefined`
disabled	`boolean`	Whether the option is disabled.	`false`
selected	`boolean`	Whether the option is selected by default.	`false`

Option group objects

Prop	Options	Description	Default
tag	`"optgroup"`	Must be `optgroup` to identify this as an option group.	`undefined`
label	`string`	The label for the group.	`undefined`
disabled	`boolean`	Whether the entire group is disabled.	`false`
options	`array`	Array of option objects within this group.	`[]`

Example

const selectOptions = [
  { tag: 'option', text: 'Select an option', disabled: true, selected: true },
  {
    tag: 'optgroup',
    label: 'Fruits',
    options: [
      { tag: 'option', text: 'Apple', value: 'apple' },
      { tag: 'option', text: 'Banana', value: 'banana' }
    ]
  }
];

Slots

Slot	Description
`leadingIcon`	An icon to display at the start of the select.

Using `pie-icons-webc` with the `pie-select` icon slot

We recommend using pie-icons-webc when using the icon slot. Here is an example of how you would do this:

<!--
  Note that pie-select and the icons that you want to use will need to be imported as components into your application.
  See the `pie-icons-webc` README for more info on importing these icons.
-->
<pie-select>
    <icon-vegan slot="leadingIcon"></icon-vegan>
</pie-select>

Events

Event	Description
`change`	Fires when the selected option is changed.

Importing and usage in templates

For HTML and Vue:

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

<pie-select
    name="my-select"
    :options="[
      { tag: 'option', text: 'Select an option' },
      { tag: 'option', text: 'Option 1', value: 'option1' }
    ]">
</pie-select>

For React Applications:

import { PieSelect } from '@justeattakeaway/pie-webc/react/select.js';

<PieSelect
    name="my-select"
    options={[
      { tag: 'option', text: 'Select an option' },
      { tag: 'option', text: 'Option 1', value: 'option1' }
    ]}>
</PieSelect>

Forms usage

It is essential that when using the select component inside a form, you provide a name attribute. HTML forms create key/value pairs for select data based on the name attribute, which is crucial for native form submission.

Validation

The select 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 select = document.querySelector('pie-select');
console.log(select.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 select 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-select
  id="my-select"
  required>
</pie-select>

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

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

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

Displaying error messages

To display validation messages, you can use the assistiveText and status properties on the select component. The assistiveText property is used to display a message below the select, and the status property is used to set the visual state of the select. The status property can be set to error, or you can omit providing a status to display the assistiveText in a neutral state.

<pie-select
  name="details"
  assistiveText="Please select an option"
  status="error">
</pie-select>