Skip to content
Pelatform UI

Data input

Combobox

Choose one option from a searchable list: a native select with a selection field and a dropdown search.

Class nameTypeDescription
comboboxplf:comboboxComponentWraps the native select
combobox-nativeplf:combobox-nativePartThe native select that keeps the value
combobox-controlplf:combobox-controlPartThe field the script adds
combobox-displayplf:combobox-displayPartThe read-only value input the script adds
combobox-inputplf:combobox-inputPartThe search input the script adds
combobox-searchplf:combobox-searchPartThe search row the script adds
combobox-toggleplf:combobox-togglePartThe open button the script adds
combobox-clearplf:combobox-clearPartThe clear button the script adds
combobox-indicatorplf:combobox-indicatorPartAn option's check the script adds
combobox-iconplf:combobox-iconPartAn icon the script adds or copies from the template
combobox-chevronplf:combobox-chevronPartThe open button's chevron the script adds
combobox-clear-iconplf:combobox-clear-iconPartThe clear button's icon the script adds
combobox-search-iconplf:combobox-search-iconPartThe search row's icon the script adds
combobox-checkplf:combobox-checkPartThe check mark in an option's indicator
combobox-popupplf:combobox-popupPartThe dropdown the script adds
combobox-listplf:combobox-listPartThe option list the script adds
combobox-groupplf:combobox-groupPartAn option group the script adds
combobox-group-labelplf:combobox-group-labelPartA group's title the script adds
combobox-optionplf:combobox-optionPartAn option the script adds
combobox-labelplf:combobox-labelPartAn option's label the script adds
combobox-detailplf:combobox-detailPartAn option's secondary text the script adds
combobox-emptyplf:combobox-emptyPartThe no-results message the script adds
combobox-statusplf:combobox-statusPartThe screen-reader status the script adds
combobox-smplf:combobox-smSizeSmall
combobox-lgplf:combobox-lgSizeLarge

Default

Label the native select and give its options unique values; multiple and a size above 1 are not supported, so use Multi Select for several values.

Open the dropdown to search. Arrow keys browse; Enter chooses; Escape cancels your search.

Selected option

Selection is marked independently from the keyboard-active option.

Groups

Search across both groups. Group titles organize choices; only tools can be selected.

Sizes

Invalid

Set aria-invalid and aria-describedby on the native select: the script copies them to the field it adds.

Error: choose a workspace before continuing.

Disabled

Disable the native select or its <fieldset>; the field the script adds follows it.

Disabled workspace

Native disabled fieldset semantics remain in effect.

Empty list

Open the list to review its empty state. Unmatched searches also show an empty message.

Options from a request

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

Server search

With data-plf-server-search, your plf:combobox:search handler answers the typed text: during the event, pass event.detail.respond() an array of { value, label, detail } or a promise of one. The options join the select, and the chosen one stays there, so the form submits it.

Phone number

Search a country, ISO code or dial code. Enter the national number without the country code.

data-plf-phone-input removes a typed dial code and the country’s data-plf-trunk-prefix, so 0857… is sent as 857…. Leave the prefix out where the 0 belongs to the number, as in Italy, and validate on the server.

JavaScript

Combobox 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">
<link rel="stylesheet" href="icons/icons.min.css">
<script src="pelatform-ui.min.js" defer></script>
<link rel="stylesheet" href="pelatform-ui.prefixed.min.css">
<link rel="stylesheet" href="icons/icons.prefixed.min.css">
<script src="pelatform-ui.min.js" defer></script>

Hooks

Attribute Purpose
data-plf-combobox Marks the combobox wrapper
data-plf-placeholder On the wrapper: text shown while no value is chosen; the empty option’s text by default, else Select an option…
data-plf-search-placeholder On the wrapper: text in the empty search field; Search options… by default
data-plf-empty On the wrapper: message when nothing matches; No options found. by default
data-plf-clearable On the wrapper: adds a clear button that chooses the empty option
data-plf-server-search On the wrapper: typing asks your plf:combobox:search handler for options instead of filtering the select’s own
data-plf-min-length On the wrapper: characters typed before a server search; 1 by default, and 0 searches as the dropdown opens
data-plf-searching, data-plf-search-error On the wrapper: messages while a server search waits and when it fails; Searching… and Options could not be loaded. by default
<template data-plf-combobox-icon> In the wrapper: the icon shown before the value, an icon class or an SVG; a template without the hook holds an SVG
data-plf-label On an option: the label shown in the field and list
data-plf-display On an option: shorter text for the closed field, such as a flag and dial code; the label by default
data-plf-detail On an option: secondary text, such as a code, that is also searched
data-plf-keywords On an option: extra words that match the search

Methods

Method Behavior
PLF.Combobox.getOrCreateInstance(element) Returns the instance, creating it for valid markup
PLF.Combobox.getInstance(element) Returns the instance or null
instance.open(), instance.close() Open or close the dropdown; return false when nothing changes or the event is canceled
instance.select(value) Chooses an option and closes the dropdown; returns false for an unknown, disabled or current value
instance.destroy() Restores the native select; the value stays

The list follows the native select: options you add, remove or rename update it while their values stay unique.

Events

Event When
plf:combobox:before-open, plf:combobox:open Before and after the dropdown opens; the first is cancelable
plf:combobox:before-close, plf:combobox:close Before and after the dropdown closes; the first is cancelable
plf:combobox:before-change, plf:combobox:change Before and after a new value; the first is cancelable
plf:combobox:search With data-plf-server-search, 300 ms after typing stops

Each event’s detail:

Property Events Value
instance All The Combobox instance
reason All api, trigger or keyboard
trigger All The element used, such as the field, an option or the clear button, otherwise null
previousValue before-change, change The value before the change
value before-change, change The new value
query search The typed text
signal search An AbortSignal that aborts when a newer search starts or the dropdown closes
respond(results) search Answers the search during the event, with an array of options or a promise of one

A choice also fires native input and change on the select; a native input or change your code dispatches fires only plf:combobox:change.

Keyboard

Key Action
Enter, Space, Arrow Down, Arrow Up On the field: open the dropdown and focus its search
Letters In the search: filter the list
Arrow Down, Arrow Up Move through enabled options, wrapping at the ends
Enter Chooses the active option and closes the dropdown
Escape Closes the dropdown without choosing
Tab Closes the dropdown without choosing; from the field, moves to the clear button when shown

Phone input

PhoneInput cleans the number as it changes, on paste and when the country changes.

Hook or method Purpose
data-plf-phone-input On the input-group: one country select and one type="tel" input
data-plf-detail On an option: the dial code, such as +62, removed when typed as +62 or 0062
data-plf-trunk-prefix On an option: the prefix to remove for that country, such as 0
PLF.PhoneInput.getOrCreateInstance(element), PLF.PhoneInput.getInstance(element) Return the instance
instance.normalize() Cleans a number your code set; returns whether it changed
instance.destroy() Stops cleaning; the number stays

React

Combobox from @pelatform/react renders the native select and what the script adds from its option and optgroup children, which take the option attributes above; inside a Field its field takes the label, help and error.

Prop Values Default
size sm, lg The default size
value The chosen option’s value, which the application changes in onValueChange Its own state
defaultValue The value it starts with when the application does not set value The first enabled option
onValueChange (value), called when an option, Clear or a native change chooses a value None
open true or false, which the application changes in onOpenChange Its own state
defaultOpen true starts with the dropdown open false
onOpenChange (open, reason), with trigger or keyboard None
clearable true adds the clear button false
icon An Icon before the value None
placeholder Text while no value is chosen The empty option’s text, else Select an option…
searchPlaceholder Text in the empty search field Search options…
emptyText Message when nothing matches No options found.
onSearch (query, signal), called 300 ms after typing stops, returning { value, label, detail } options or a promise of them, which take the children’s place in the list None
showLabel, hideLabel The open button’s name while the dropdown is closed and open Show options, Hide options
clearLabel The clear button’s name Clear selection
listLabel The list’s name Options

The other props are the native select’s, ref included; className adds classes to the combobox wrapper, such as input-group-combobox, and with aria-label the field leaves a Field’s label to its other control, as in the phone number.

CSS variables

Variable Default
--plf-combobox-height Minimum height: 2.25rem (36px); 2rem (32px) with combobox-sm, 2.5rem (40px) with combobox-lg; the list’s rows take it too
--plf-combobox-radius --plf-radius-lg, 0.5rem (8px)
--plf-combobox-border --plf-color-input
--plf-combobox-hover-border --plf-combobox-border, otherwise --plf-color-border
--plf-combobox-invalid-border --plf-color-danger
--plf-combobox-bg, --plf-combobox-color --plf-color-field, --plf-color-text
--plf-combobox-icon-size --plf-control-icon-size (16px); 1em (14px) with combobox-sm, 18px with combobox-lg
--plf-combobox-focus-width, --plf-combobox-focus-color --plf-focus-width (2px), --plf-focus-color
--plf-combobox-focus-offset 0px, so the ring sits just outside the border
--plf-combobox-popup-width The field’s width, at least 16rem (256px)
--plf-combobox-popup-max-height 18rem (288px)
--plf-combobox-popup-bg, --plf-combobox-popup-border --plf-color-surface-elevated, --plf-color-border-subtle
--plf-combobox-search-bg, --plf-combobox-group-bg --plf-color-surface-raised
--plf-combobox-group-color --plf-color-text-muted
--plf-combobox-active-bg, --plf-combobox-active-color --plf-color-surface-muted, --plf-color-text
--plf-combobox-active-border --plf-color-input
--plf-input-group-combobox-width 7.25rem (116px), the width of an input-group-combobox segment

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