Skip to content
Pelatform UI

Data input

Multi Select

Choose several options from a searchable list, shown as removable chips.

Class nameTypeDescription
multi-selectplf:multi-selectComponentA native multiple select; the script adds a search field, chips and a list after it
multi-select-controlplf:multi-select-controlPartThe field the script adds
multi-select-chipsplf:multi-select-chipsPartThe row of chips and search the script adds
multi-select-chipplf:multi-select-chipPartA chosen value's chip the script adds
multi-select-chip-labelplf:multi-select-chip-labelPartA chip's label the script adds
multi-select-avatarplf:multi-select-avatarPartAn option's initials the script adds
multi-select-removeplf:multi-select-removePartA chip's remove button the script adds
multi-select-inputplf:multi-select-inputPartThe search field the script adds
multi-select-toggleplf:multi-select-togglePartThe show-options button the script adds
multi-select-clearplf:multi-select-clearPartThe clear button the script adds
multi-select-indicatorplf:multi-select-indicatorPartAn option's check mark the script adds
multi-select-iconplf:multi-select-iconPartAn icon the script adds
multi-select-popupplf:multi-select-popupPartThe popup the script adds
multi-select-listplf:multi-select-listPartThe option list the script adds
multi-select-optionplf:multi-select-optionPartAn option the script adds
multi-select-labelplf:multi-select-labelPartAn option's label the script adds
multi-select-detailplf:multi-select-detailPartAn option's second line the script adds
multi-select-textplf:multi-select-textPartThe label and detail column the script adds
multi-select-emptyplf:multi-select-emptyPartThe no-match message the script adds
multi-select-statusplf:multi-select-statusPartThe screen reader status the script adds
multi-select-smplf:multi-select-smSizeSmall
multi-select-lgplf:multi-select-lgSizeLarge

Default

Options need unique, nonempty values and no <optgroup>; read the values with FormData.getAll(name).

Select at least one category. Click a selected option again to remove it.

Sizes

Members

Search by name, email or team. Pending invitations cannot be selected.

Options from a request

The list follows the native select, so add the options your request returns to it.

JavaScript

Multi Select needs JavaScript. The Full script (pelatform-ui.min.js) starts every component on page load, with no code of your own; with ESM imports, call init() yourself, as in Installation. For markup you add later, see Dynamic content.

<link rel="stylesheet" href="pelatform-ui.min.css">
<script src="pelatform-ui.min.js" defer></script>
<link rel="stylesheet" href="pelatform-ui.prefixed.min.css">
<script src="pelatform-ui.min.js" defer></script>

Hooks

Attribute Purpose
data-plf-multi-select On a multiple select: adds the search field, chips and list after it; the field takes the select’s classes, style and hidden
data-plf-placeholder On the select: text in the search field; Search and select… by default
data-plf-empty On the select: message when nothing matches; No options found. by default
data-plf-label On an option: the label shown in the list and chip
data-plf-detail On an option: a second line that is also searched
data-plf-initials On an option: decorative initials before the label
data-plf-keywords On an option: extra words that match the search

Methods

Method Behavior
PLF.MultiSelect.getOrCreateInstance(element) Returns the instance, creating it for valid markup
PLF.MultiSelect.getInstance(element) Returns the instance or null
instance.open(), instance.close() Open or close the list; return false when nothing changes or the event is canceled
instance.getValue() Returns the chosen values in option order
instance.setValue(values) Sets the chosen values from an array of strings; returns false for unknown or duplicate values, or when a disabled option would change
instance.toggle(value) Adds or removes one value
instance.clear() Removes every value except those on disabled options
instance.destroy() Removes the field, chips and list; the select keeps its values

Events

Event When
plf:multi-select:before-open, plf:multi-select:open Before and after the list opens; the first is cancelable
plf:multi-select:before-close, plf:multi-select:close Before and after the list closes; the first is cancelable
plf:multi-select:before-change, plf:multi-select:change Before and after the values change; the first is cancelable

Each event’s detail:

Property Events Value
instance All The Multi Select instance
reason All api, trigger, keyboard, or native for a native input or change your code dispatches, which skips the before event
trigger All The search field, the clicked button or option, the select for native, or null from a method or a press or focus outside
previousValue before-change, change The chosen values before the change, an array
value before-change, change The chosen values after the change, an array

A change also fires native input and change on the select.

Keyboard

Key Action
Letters, Space Type in the search and filter the list
Arrow Down, Arrow Up Open the list, then move through enabled options, wrapping at the ends
Enter Opens the list; while open, adds or removes the active option and keeps the list open
Backspace In an empty search, removes the last chosen value
Escape Closes the list and clears the search; chosen values stay
Tab Closes the list and moves on

React

MultiSelect from @pelatform/react renders the native multiple select around its option children, with the field, chips and list the script adds; inside a Field its search field takes the field’s label, help and error.

Prop Values Default
size sm, lg The default size
value An array of the chosen values, which the application changes in onValueChange Its own state
defaultValue The values it starts with when the application does not set value None
onValueChange (values), called with the chosen values, in option order, when they change None
open true or false, which the application changes in onOpenChange Its own state
defaultOpen true starts open when the application does not set open false
onOpenChange (open, reason), called when the list opens or closes: trigger (the field, the toggle or a press outside) or keyboard (a key or the focus leaving) None
placeholder The search field’s text Search and select…
emptyText The message when nothing matches No options found.
clearLabel The clear button’s name Clear selection
removeLabel (label) => string, a chip’s remove button’s name Remove {label}
showLabel, hideLabel The toggle’s name while the list is closed and while it is open Show options, Hide options

An option takes data-plf-label, data-plf-detail, data-plf-initials and data-plf-keywords, as in HTML. The other props are a native select’s, className and ref included; the search field takes id, which the label names.

CSS variables

Override on a root or a container; on the select itself they reach the field, not the list.

Variable Default
--plf-multi-select-height Minimum height: 2.25rem (36px); 2rem (32px) with multi-select-sm, 2.5rem (40px) with multi-select-lg; the list’s rows take it too
--plf-multi-select-padding-block, --plf-multi-select-padding-inline 0.25rem (4px) and 0.75rem (12px); 0.125rem (2px) and 0.5rem (8px) with multi-select-sm, 0.25rem (4px) and 1rem (16px) with multi-select-lg
--plf-multi-select-icon-size --plf-control-icon-size (16px); 14px with multi-select-sm, 18px with multi-select-lg
--plf-multi-select-radius --plf-radius-lg, 0.5rem (8px)
--plf-multi-select-border --plf-color-input
--plf-multi-select-hover-border --plf-multi-select-border, otherwise --plf-color-border
--plf-multi-select-invalid-border --plf-color-danger
--plf-multi-select-bg --plf-color-field
--plf-multi-select-focus-width, --plf-multi-select-focus-color, --plf-multi-select-focus-offset The shared focus ring
--plf-multi-select-chip-border, --plf-multi-select-chip-bg --plf-color-border-subtle, --plf-color-surface-muted
--plf-multi-select-popup-width 22rem (352px)
--plf-multi-select-popup-max-height 18rem (288px)
--plf-multi-select-popup-bg, --plf-multi-select-popup-border --plf-color-surface-elevated, --plf-color-border-subtle
--plf-multi-select-active-bg --plf-color-surface-muted

Built with Pelatform UIv0.1.0

Components

Getting started

Foundations

Components

Actions

Data display

Navigation

Feedback

Data input

Layout

Advanced

Integrations

Blocks

Application

Authentication

Icons