The Placer Toolkit alpha has arrived! 🎉
Plenty of changes are coming your way—some big, some breaking, some even nuclear! Beware the changelog…

Bring it on!

Select

<pc-select>

0.5.1

experimental

Selects allow you to choose items from a menu of predefined options.

<pc-select>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
    <pc-option value="option-4">Option 4</pc-option>
    <pc-option value="option-5">Option 5</pc-option>
    <pc-option value="option-6">Option 6</pc-option>
</pc-select>

Code

Edit

This component works well with standard <form> elements. Please refer to the form controls page to learn more about form submission and client‐side validation.

Demos#

Labels#

Use the label attribute to give the select an accessible label. For labels that contain HTML, use the label slot instead.

<pc-select label="Select an option">
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Hints#

Add a descriptive hint to a select with the hint attribute. For hints that contain HTML, use the hint slot instead.

<pc-select label="Experience" hint="Please tell us your skill level.">
    <pc-option value="novice">Novice</pc-option>
    <pc-option value="intermediate">Intermediate</pc-option>
    <pc-option value="advanced">Advanced</pc-option>
</pc-select>

Code

Edit

Placeholders#

Use the placeholder attribute to add a placeholder.

<pc-select placeholder="Select one">
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Clearable#

Use the clearable attribute to make the select clearable. The clear button only appears when an option is selected.

<pc-select value="option-1" clearable>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Filled#

Add the filled attribute to draw a filled select.

<pc-select filled>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Pill#

Use the pill attribute to give selects a pill‐shaped look.

<pc-select pill>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Disabled#

Use the disabled attribute to disable the select.

<pc-select placeholder="Disabled" disabled>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Multiple options#

To allow multiple options to be selected, use the multiple attribute. It’s a good practice to use the clearable attribute as well when this option is enabled. To set multiple values at once, set value to a space‐delimited list of values.

<pc-select label="Select a few options" value="option-1 option-2 option-3" multiple clearable>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
    <pc-option value="option-4">Option 4</pc-option>
    <pc-option value="option-5">Option 5</pc-option>
    <pc-option value="option-6">Option 6</pc-option>
</pc-select>

Code

Edit

Multi‐select options may wrap, causing the select to expand vertically. You can use the max-options-visible attribute to control the maximum number of selected options to show at once.

Setting initial values#

Use the value attribute to set the initial selection.

When using the multiple attribute, the value attribute uses space‐delimited values to select more than one option. Because of this, <pc-option> values cannot contain spaces. If you’re accessing the value property through JavaScript, it will be an array.

<pc-select value="option-1 option-2 option-3" multiple clearable>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
    <pc-option value="option-4">Option 4</pc-option>
    <pc-option value="option-5">Option 5</pc-option>
    <pc-option value="option-6">Option 6</pc-option>
</pc-select>

Code

Edit

Grouping options#

Use the Divider component to group listbox items visually. You can also use the <small> tag to provide labels, but they won’t be announced by most assistive devices.

<pc-select>
    <small>Section 1</small>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
    <pc-divider></pc-divider>
    <small>Section 2</small>
    <pc-option value="option-4">Option 4</pc-option>
    <pc-option value="option-5">Option 5</pc-option>
    <pc-option value="option-6">Option 6</pc-option>
</pc-select>

Code

Edit

Sizes#

Use the size attribute to change the select’s size.

<pc-select size="small" placeholder="Small">
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

<br />

<pc-select size="medium" placeholder="Medium">
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

<br />

<pc-select size="large" placeholder="Large">
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Placement#

The preferred placement of the select’s listbox can be set with the placement attribute. The actual position may vary to ensure the panel remains in the viewport.

<pc-select placement="top">
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Prefixes and suffixes#

Use the prefix and suffix slots to add presentational icons and text. Avoid slotting in interactive elements, such as buttons and links.

<pc-select size="small" placeholder="Small" clearable>
    <pc-icon
        library="default"
        icon-style="solid"
        name="house"
        slot="prefix"
    ></pc-icon>
    <pc-badge slot="suffix">New</pc-badge>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

<br />

<pc-select size="medium" placeholder="Medium" clearable>
    <pc-icon
        library="default"
        icon-style="solid"
        name="house"
        slot="prefix"
    ></pc-icon>
    <pc-badge slot="suffix">New</pc-badge>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

<br />

<pc-select size="large" placeholder="Large" clearable>
    <pc-icon
        library="default"
        icon-style="solid"
        name="house"
        slot="prefix"
    ></pc-icon>
    <pc-badge slot="suffix">New</pc-badge>
    <pc-option value="option-1">Option 1</pc-option>
    <pc-option value="option-2">Option 2</pc-option>
    <pc-option value="option-3">Option 3</pc-option>
</pc-select>

Code

Edit

Custom tags#

When multiple options can be selected, you can provide custom tags by passing a function to the getTag property. Your function can return a string of HTML, a Lit template or an HTMLElement. The getTag() function will be called for each option. The first argument is a <pc-option> element and the second argument is the tag’s index (its position in the tag list).

Remember that custom tags are rendered in a shadow root. To style them, you can use the style attribute in your template or you can add your own parts and target them with the ::part() selector.

<pc-select
    class="custom-tags"
    placeholder="Select one"
    value="e-mail phone"
    multiple
    clearable
>
    <pc-option value="e-mail">
        <pc-icon
            library="default"
            icon-style="solid"
            name="envelope"
            slot="prefix"
        ></pc-icon>
        E‐mail
    </pc-option>
    <pc-option value="phone">
        <pc-icon
            library="default"
            icon-style="solid"
            name="phone"
            slot="prefix"
        ></pc-icon>
        Phone
    </pc-option>
    <pc-option value="chat">
        <pc-icon
            library="default"
            icon-style="solid"
            name="message"
            slot="prefix"
        ></pc-icon>
        Chat
    </pc-option>
</pc-select>

<script>
    const select = document.querySelector(".custom-tags");

    select.getTag = (option, index) => {
        const name = option.querySelector('pc-icon[slot="prefix"]').name;

        // A string, Lit template or HTMLElement can be returned here
        return `
            <pc-tag removable>
                <pc-icon
                    library="default"
                    icon-style="solid"
                    name="${name}"
                    style="padding-inline-end: var(--pc-spacing-s)"
                ></pc-icon>
                ${option.getTextLabel()}
            </pc-tag>
        `;
    };
</script>

Code

Edit

Lazy loading options#

Lazy loading options is very hard to get right. <pc-select> largely follows how a native <select> works.

Here are the following conditions:

If a <pc-select> is created without any options, but is given a value attribute, its value will be "", and then when options are added, if any of the options have a value equal to the <pc-select> value, the value of the <pc-select> will be equal that of the option.

For example, <pc-select value="foo"> will have a value of "" until <pc-option value="foo">Foo</pc-option> connects, at which point its value will become "foo" when submitting.

If a <pc-select multiple> with an initial value has multiple values, but only some of the options are present, it will only respect the options that are present, and if a selected option is loaded in later, and the value of the select has not changed via user interaction or direct property assignment, it will add the selected option ot the form value and to the .value of the select.

This can be hard to conceptualise, so here’s a fairly large example showing how lazy‐loaded options work with <pc-select> and <pc-select multiple> when given initial value attributes. Feel free to play around with it in this code demo.

<form id="lazy-options-example">
    <div>
        <pc-select name="select-1" value="foo" label="Single select (with existing options)">
            <pc-option value="bar">Bar</pc-option>
            <pc-option value="baz">Baz</pc-option>
        </pc-select>
        <br />
        <pc-button type="button">Add “foo” option</pc-button>
    </div>

    <br />

    <div>
        <pc-select
            label="Single select (with no existing options)"
            name="select-2"
            value="foo"
        ></pc-select>
        <br />
        <pc-button type="button">Add “foo” option</pc-button>
    </div>

    <br />

    <div>
        <pc-select
            label="Multiple select (with existing options)"
            name="select-3"
            value="foo bar baz"
            multiple
        >
            <pc-option value="bar">Bar</pc-option>
            <pc-option value="baz">Baz</pc-option>
        </pc-select>
        <br />
        <pc-button type="button">Add “foo” option</pc-button>
    </div>

    <br />

    <div>
        <pc-select
            label="Multiple select (with no existing options)"
            name="select-4"
            value="foo"
            multiple
        ></pc-select>
        <br />
        <pc-button type="button">Add “foo” option</pc-button>
    </div>

    <br />

    <div style="display: flex; gap: var(--pc-spacing-s)">
        <pc-button appearance="primary" type="submit">Show FormData</pc-button>
        <pc-button type="reset">Reset</pc-button>
    </div>

    <br />

    <pre hidden><code id="lazy-options-example-form-data"></code></pre>
</form>

<script>
    function addFooOption(e) {
        const addFooButton = e.target.closest('pc-button[type="button"]');

        if (!addFooButton) {
            return;
        }

        const select = addFooButton.parentElement.querySelector("pc-select");

        if (select.querySelector('pc-option[value="foo"]')) {
            return;
        }

        const option = document.createElement("pc-option");

        option.setAttribute("value", "foo");
        option.innerText = "Foo";
        select.append(option);
    }

    function handleLazySubmit (event) {
        event.preventDefault();

        const formData = new FormData(event.target);
        const codeElement = document.querySelector("#lazy-options-example-form-data");
        const obj = {};

        for (const key of formData.keys()) {
            const value = formData.getAll(key).length > 1 ? formData.getAll(key) : formData.get(key);
            obj[key] = value;
        }

        codeElement.textContent = JSON.stringify(obj, null, 4);
        const preElement = codeElement.parentElement;
        preElement.removeAttribute("hidden");
    }

    const container = document.querySelector("#lazy-options-example");

    container.addEventListener("click", addFooOption);
    container.addEventListener("submit", handleLazySubmit);
</script>

Code

Edit

Be sure you trust the content you are outputting! Passing unsanitised user input to getTag() can result in XSS vulnerabilities.

Properties#

Name	Description	Default
`name`	The name of the select, submitted as a name/value pair with form data. Type: `string`	`""`
`defaultValue` `value`	The default value of the select. Primarily used for resetting the select. Type: `string \| string[]`	`""`
`size`	The select’s size. Type: `"small" \| "medium" \| "large"`	`"medium"`
`placeholder`	Placeholder text to show as a hint when the select is empty. Type: `string`	`""`
`multiple`	Allows more than one option to be selected. Type: `boolean`	`false`
`maxOptionsVisible` `max-options-visible`	The maximum number of selected options to show when the `multiple` attribute is true. After the maximum limit, “+number” will be shown to indicate the number of additional items that are selected. Set the value to 0 to remove the limit. Type: `number`	`3`
`disabled`	Disables the select. Type: `boolean`	`false`
`clearable`	Adds a clear button when the select is not empty. Type: `boolean`	`false`
`open`	Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can use the `show()` and `hide()` methods and this attribute will reflect the select’s open state. Type: `boolean`	`false`
`filled`	Draws a filled select combobox. Type: `boolean`	`false`
`pill`	Draws a pill‐style select. Type: `boolean`	`false`
`label`	The select’s label. If you need to display HTML, use the `label` slot instead. Type: `string`	`""`
`placement`	The preferred placement of the select’s listbox. Note that the actual placement may vary to keep the listbox inside of the viewport. Type: `"top" \| "bottom"`	`"bottom"`
`hint`	The select’s hint. If you need to display HTML, use the `hint` slot instead. Type: `string`	`""`
`form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. Type: `string`	`""`
`required`	Indicates if the select must be filled in or not. Type: `boolean`	`false`
`getTag`	A function that customises the tags to be rendered when the `multiple` attribute is true. The first parameter is the option, the second parameter is the current tag’s index. The function should either return either a Lit `TemplateResult` or a string containing trusted HTML of the symbol to render at the specified value. Type: `( option: PcOption, index: number, ) => TemplateResult \| string \| HTMLElement`	‐
`value`	The current value of the select, submitted as a name/value pair with form data. When the `multiple` attribute is true, the `value` attribute will be a space‐delimited list of values based on the options selected, and the `value` property will be an array. For this reason, values must not contain spaces.	‐
`validity`	Gets the validity state object.	‐
`validationMessage`	Gets the validation message.	‐
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about attributes and properties.

Slots#

Name	Description
(default)	The listbox options. Only `<pc-option>` and `<pc-divider>` elements can be slotted here. You can use `<pc-divider>` to group items visually.
`label`	The select’s label. Alternatively, you can use the `label` attribute.
`prefix`	Used to prepend a presentational icon or similar element to the combobox.
`suffix`	Used to append a presentational icon or similar element to the combobox.
`clear-icon`	An icon to use in place of the default clear icon.
`expand-icon`	The icon to show when the select is expanded and collapsed. Rotates on open and close.
`hint`	Text that describes how to use the select. Alternatively, you can use the `hint` attribute.

Learn more about using slots.

Methods#

Name	Description	Arguments
`show()`	Shows the listbox.	‐
`hide()`	Hides the listbox.	‐
`checkValidity()`	Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.	‐
`getForm()`	Gets the associated form, if one exists.	‐
`reportValidity()`	Checks for validity and shows the browser’s validation message if the select is invalid.	‐
`setCustomValidity()`	Sets a custom validation message. Pass an empty string to restore validity.	`message: string`
`focus()`	Focuses the select.	`options: FocusOptions`
`blur()`	Unfocuses the select (i.e., blurs it).	‐

Learn more about methods.

Events#

Name	Description	Event detail
`pc-input`	Emitted when the select receives input.	‐
`pc-change`	Emitted when the select’s value changes.	‐
`pc-clear`	Emitted when the select’s value is cleared.	‐
`pc-focus`	Emitted when the select gains focus.	‐
`pc-blur`	Emitted when the select loses focus.	‐
`pc-show`	Emitted when the select’s menu opens.	‐
`pc-after-show`	Emitted after the select’s menu opens and all animations are complete.	‐
`pc-hide`	Emitted when the select’s menu closes.	‐
`pc-after-hide`	Emitted after the select’s menu closes and all animations are complete.	‐
`pc-invalid`	Emitted when the select has been checked for validity and its constraints aren’t satisfied.	‐

Learn more about events.

Parts#

Name	Description
`form-control`	The form control that wraps the label, input and hint.
`label`	The select’s label.
`input`	The select’s input.
`hint`	The select’s hint.
`combobox`	The container the wraps the prefix, suffix, combobox, clear icon and expand button.
`prefix`	The container that wraps the prefix slot.
`suffix`	The container that wraps the suffix slot.
`display-input`	The element that displays the selected option’s label, an `<input>` element.
`listbox`	The listbox container where options are slotted.
`tags`	The container that houses option tags when `multiselect` is used.
`tag`	The individual tags that represent each multiselect option.
`tag-base`	The tag’s base part.
`tag-content`	The tag’s content part.
`tag-remove-button`	The tag’s remove button.
`tag-remove-button-base`	The tag’s remove button base part.
`clear-button`	The clear button.
`expand-icon`	The container that wraps the expand icon.

Learn more about customising CSS parts.

Importing#

If you’re using the autoloader or the standard loader, you can skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/select/select.js"></script>

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/select/select.js";

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

import "placer-toolkit/dist/components/select/select.js";

Dependencies#

This component automatically imports these components: