Light Dark System

Select

<p-select> | PSelect
Since 1.0 stable

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

Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 
<p-select show-search clearable multiple placeholder="Select">
  <p-option value="option-1">Option 1</p-option>
  <p-option value="option-2">Option 2</p-option>
  <p-option value="option-3">Option 3</p-option>
  <p-option value="option-4">Option 4</p-option>
  <p-option value="option-5">Option 5</p-option>
  <p-option value="option-6">Option 6</p-option>
</p-select>

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
    <POption value="option-4">Option 4</POption>
    <POption value="option-5">Option 5</POption>
    <POption value="option-6">Option 6</POption>
  </PSelect>
);

Examples

Labels

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

Option 1 Option 2 Option 3 
<p-select label="Select one">
  <p-option value="option-1">Option 1</p-option>
  <p-option value="option-2">Option 2</p-option>
  <p-option value="option-3">Option 3</p-option>
</p-select>

<script>
  const  select = document.querySelector(.select)

</script>

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect label="Select one">
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PSelect>
);

Help Text

Add descriptive help text to a select with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

Novice Intermediate Advanced 
<p-select label="Experience" help-text="Please tell us your skill level.">
  <p-option value="1">Novice</p-option>
  <p-option value="2">Intermediate</p-option>
  <p-option value="3">Advanced</p-option>
</p-select>

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect label="Experience" help-text="Please tell us your skill level.">
    <POption value="1">Novice</POption>
    <POption value="2">Intermediate</POption>
    <POption value="3">Advanced</POption>
  </PSelect>
);

Placeholders

Use the placeholder attribute to add a placeholder.

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect placeholder="Select one">
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PSelect>
);

The show-search attribute is a boolean attribute that enables the search functionality within the <p-select> component. When set to true, users can type to filter the options.

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect placeholder="Select one">
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PSelect>
);

Clearable

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

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect placeholder="Clearable" clearable>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PSelect>
);

Filled Selects

Add the filled attribute to draw a filled select.

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect filled>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PSelect>
);

Pill

Use the pill attribute to give selects rounded edges.

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect pill>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PSelect>
);

Disabled

Use the disabled attribute to disable a select.

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect placeholder="Disabled" disabled>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PSelect>
);

Multiple

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

Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 Option 7 Option 8 Option 9 Option 10 
<p-select label="Select a Few" value="option-1 option-2 option-3" multiple clearable max-options-visible="4" show-search>
  <p-option value="option-1">Option 1</p-option>
  <p-option value="option-2">Option 2</p-option>
  <p-option value="option-3">Option 3</p-option>
  <p-option value="option-4">Option 4</p-option>
  <p-option value="option-5">Option 5</p-option>
  <p-option value="option-6">Option 6</p-option>
  <p-option value="option-7">Option 7</p-option>
  <p-option value="option-8">Option 8</p-option>
  <p-option value="option-9">Option 9</p-option>
  <p-option value="option-10">Option 10</p-option>
</p-select>

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect label="Select a Few" value={["option-1", "option-2", "option-3"]} multiple clearable>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
    <POption value="option-4">Option 4</POption>
    <POption value="option-5">Option 5</POption>
    <POption value="option-6">Option 6</POption>
  </PSelect>
);

Tag mode

  • Enable tag mode:

    • The tag-mode attribute enables users to add new tags by pressing the “Enter” key after typing a new tag.
    • This feature is useful when you want to allow users to add new items that are not already included in the list of options.
    • Note that in tag mode, the component will not validate whether the user’s input matches any of the available options.

  • Good practice to use clearable:

    • The clearable attribute is a good practice to use when the multiple attribute is enabled.
    • This allows users to remove all selected options at once by clicking the clear icon.

  • Set multiple values at once:

    • To set multiple values at once, set the value attribute to a space-delimited list of values.
Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 Option 7 Option 8 Option 9 Option 10 
<p-select label="Select a Few" value="option-1 option-2 option-3" multiple clearable max-options-visible="4" tag-mode show-search>
  <p-option value="option-1">Option 1</p-option>
  <p-option value="option-2">Option 2</p-option>
  <p-option value="option-3">Option 3</p-option>
  <p-option value="option-4">Option 4</p-option>
  <p-option value="option-5">Option 5</p-option>
  <p-option value="option-6">Option 6</p-option>
  <p-option value="option-7">Option 7</p-option>
  <p-option value="option-8">Option 8</p-option>
  <p-option value="option-9">Option 9</p-option>
  <p-option value="option-10">Option 10</p-option>
</p-select>

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect label="Select a Few" value={["option-1", "option-2", "option-3"]} multiple clearable>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
    <POption value="option-4">Option 4</POption>
    <POption value="option-5">Option 5</POption>
    <POption value="option-6">Option 6</POption>
  </PSelect>
);

Setting Initial Values

Use the value attribute to set the initial selection.

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

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

import PDivider from 'pure-uikit/dist/react/divider';
import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect value={["option-1", "option-2"]} multiple clearable>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PSelect>
);

Grouping Options

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

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect>
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
    <POption value="option-4">Option 4</POption>
    <POption value="option-5">Option 5</POption>
    <POption value="option-6">Option 6</POption>
  </PSelect>
);

Sizes

Use the size attribute to change a select’s size. Note that size does not apply to listbox options.

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

<br />

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

<br />

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <>
    <PSelect placeholder="Small" size="small">
      <POption value="option-1">Option 1</POption>
      <POption value="option-2">Option 2</POption>
      <POption value="option-3">Option 3</POption>
    </PSelect>

    <br />

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

    <br />

    <PSelect placeholder="Large" size="large">
      <POption value="option-1">Option 1</POption>
      <POption value="option-2">Option 2</POption>
      <POption value="option-3">Option 3</POption>
    </PSelect>
  </>
);

Placement

The preferred placement of the select’s listbox can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are top and bottom.

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

import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <PSelect placement="top">
    <POption value="option-1">Option 1</POption>
    <POption value="option-2">Option 2</POption>
    <POption value="option-3">Option 3</POption>
  </PDropdown>
);

Prefix & Suffix

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

New Option 1 Option 2 Option 3
New Option 1 Option 2 Option 3
New Option 1 Option 2 Option 3 
<p-select placeholder="Small" size="small" clearable>
  <p-icon name="house" slot="prefix"></p-icon>
  <p-badge slot="suffix">New</p-badge>
  <p-option value="option-1">Option 1</p-option>
  <p-option value="option-2">Option 2</p-option>
  <p-option value="option-3">Option 3</p-option>
</p-select>
<br />
<p-select placeholder="Medium" size="medium" clearable>
  <p-icon name="house" slot="prefix"></p-icon>
  <p-badge slot="suffix">New</p-badge>
  <p-option value="option-1">Option 1</p-option>
  <p-option value="option-2">Option 2</p-option>
  <p-option value="option-3">Option 3</p-option>
</p-select>
<br />
<p-select placeholder="Large" size="large" clearable>
  <p-icon name="house" slot="prefix"></p-icon>
  <p-badge slot="suffix">New</p-badge>
  <p-option value="option-1">Option 1</p-option>
  <p-option value="option-2">Option 2</p-option>
  <p-option value="option-3">Option 3</p-option>
</p-select>

import PIcon from 'pure-uikit/dist/react/icon';
import POption from 'pure-uikit/dist/react/option';
import PSelect from 'pure-uikit/dist/react/select';

const App = () => (
  <>
    <PSelect placeholder="Small" size="small">
      <PIcon name="house" slot="prefix"></PIcon>
      <POption value="option-1">Option 1</POption>
      <POption value="option-2">Option 2</POption>
      <POption value="option-3">Option 3</POption>
    </PSelect>
    <br />
    <PSelect placeholder="Medium" size="medium">
      <PIcon name="house" slot="prefix"></PIcon>
      <POption value="option-1">Option 1</POption>
      <POption value="option-2">Option 2</POption>
      <POption value="option-3">Option 3</POption>
    </PSelect>
    <br />
    <PSelect placeholder="Large" size="large">
      <PIcon name="house" slot="prefix"></PIcon>
      <POption value="option-1">Option 1</POption>
      <POption value="option-2">Option 2</POption>
      <POption value="option-3">Option 3</POption>
    </PSelect>
  </>
);

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 an <p-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.

Email Phone Chat 
<p-select
  placeholder="Select one"
  value="email phone"
  multiple
  clearable
  class="custom-tag"
>
  <p-option value="email">
    <p-icon slot="prefix" name="envelope"></p-icon>
    Email
  </p-option>
  <p-option value="phone">
    <p-icon slot="prefix" name="telephone"></p-icon>
    Phone
  </p-option>
  <p-option value="chat">
    <p-icon slot="prefix" name="chat-dots"></p-icon>
    Chat
  </p-option>
</p-select>

<script type="module">
  const select = document.querySelector('.custom-tag');

  select.getTag = (option, index) => {
    // Use the same icon used in the <p-option>
    const name = option.querySelector('p-icon[slot="prefix"]').name;

    // You can return a string, a Lit Template, or an HTMLElement here
    return `
      <p-tag removable>
        <p-icon name="${name}" style="padding-inline-end: .5rem;"></p-icon>
        ${option.getTextLabel()}
      </p-tag>
    `;
  };
</script>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/pure-uikit@1.3.13/cdn/components/select/select.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/pure-uikit@1.3.13/cdn/components/select/select.js';

To import this component using a bundler:

import 'pure-uikit/dist/components/select/select.js';

To import this component as a React component:

import PSelect from 'pure-uikit/dist/react/select';

Slots

Name Description
(default) The listbox options. Must be <p-option> elements. You can use <p-divider> to group items visually.
label The input’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 lieu of the default clear icon.
expand-icon The icon to show when the control is expanded and collapsed. Rotates on open and close.
help-text Text that describes how to use the input. Alternatively, you can use the help-text attribute.

Learn more about using slots.

Properties

Name Description Reflects Type Default
displayLabel The display label to show in the select when no options are selected. Used when the control is not focused. string ""
currentOption The currently selected option. POption -
selectedOptions The selected options. POption[] []
maxCount
max-count 		The maximum number of options that can be selected. Defaults to -1, which means there is no limit. number -1
tagMode
tag-mode 		Indicates whether the select should operate in tag mode, where selected options are shown as tags and the user can remove them or add new tag by “Enter” after typing new tag. This property is reflected as a boolean attribute, tag-mode, on the element. boolean false
showSearch
show-search 		Indicates whether a search box should be shown for finding options quickly. This property is reflected as a boolean attribute, show-search, on the element. boolean false
name The name of the select, submitted as a name/value pair with form data. string ""
value The current value of the select, submitted as a name/value pair with form data. When multiple is enabled, 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. string | string[] ""
defaultValue The default value of the form control. Primarily used for resetting the form control. string | string[] ""
size The select’s size. "small" | "medium" | "large" "medium"
placeholder Placeholder text to show as a hint when the select is empty. string ""
multiple Allows more than one option to be selected. boolean false
maxOptionsVisible
max-options-visible 		The maximum number of selected options to show when multiple is true. After the maximum, ”+n” will be shown to indicate the number of additional items that are selected. Set to 0 to remove the limit. number 3
disabled Disables the select control. boolean false
clearable Adds a clear button when the select is not empty. 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. boolean false
hoist Enable this option to prevent the listbox from being clipped when the component is placed inside a container with overflow: auto|scroll. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios. boolean false
filled Draws a filled select. boolean false
pill Draws a pill-style select with rounded edges. boolean false
label The select’s label. If you need to display HTML, use the label slot instead. string ""
placement The preferred placement of the select’s menu. Note that the actual placement may vary as needed to keep the listbox inside of the viewport. "top" | "bottom" "bottom"
helpText
help-text 		The select’s help text. If you need to display HTML, use the help-text slot instead. 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. string ""
required The select’s required attribute. boolean false
getTag A function that customizes the tags to be rendered when multiple=true. The first argument is the option, the second is the current tag’s index. The function should return either a Lit TemplateResult or a string containing trusted HTML of the symbol to render at the specified value. (option: POption, index: number) => TemplateResult | string | HTMLElement -
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.

Events

Name React Event Description Event Detail
p-change onPChange Emitted when the control’s value changes. -
p-clear onPClear Emitted when the control’s value is cleared. -
p-input onPInput Emitted when the control receives input. -
p-focus onPFocus Emitted when the control gains focus. -
p-blur onPBlur Emitted when the control loses focus. -
p-show onPShow Emitted when the select’s menu opens. -
p-after-show onPAfterShow Emitted after the select’s menu opens and all animations are complete. -
p-hide onPHide Emitted when the select’s menu closes. -
p-after-hide onPAfterHide Emitted after the select’s menu closes and all animations are complete. -
p-invalid onPInvalid Emitted when the form control has been checked for validity and its constraints aren’t satisfied. -

Learn more about events.

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 control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message: string
focus() Sets focus on the control. options: FocusOptions
blur() Removes focus from the control. -

Learn more about methods.

Parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label’s wrapper.
form-control-input The select’s wrapper.
form-control-help-text The help text’s wrapper.
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 customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <p-icon>
  • <p-icon-button>
  • <p-popup>
  • <p-tag>