A native <select> with better CSS. Write ordinary
<option> and <optgroup> children. The component builds a <select>
around them. Forms, keyboard use, and accessibility work via the browser.
npm i -S @substrate-system/select<form>
<substrate-select label="Fruit" name="fruit" required>
<option value="">Choose a fruit</option>
<optgroup label="Citrus">
<option value="lemon">Lemon</option>
<option value="orange" selected>Orange</option>
</optgroup>
<option value="apple">Apple</option>
</substrate-select>
</form>
<script type="module">
import { SubstrateSelect } from '@substrate-system/select'
const el = document.querySelector('substrate-select')
// custom .on method
el.on('change', ev => console.log(ev.detail.value))
</script>Preact sets value as a property, because the element defines one.
import { html } from 'htm/preact'
import { SubstrateSelect } from '@substrate-system/select'
function FruitPicker ({ fruit, onChange }) {
return html`<${SubstrateSelect.TAG}
label="Fruit"
name="fruit"
value=${fruit}
onsubstrate-select:change=${ev => onChange(ev.detail.value)}
>
<option value="lemon">Lemon</option>
<option value="apple">Apple</option>
<//>`
}This exposes ESM and common JS via
package.json exports field.
import { SubstrateSelect } from '@substrate-system/select'Importing the module registers the <substrate-select> element.
require('@substrate-system/select')| Attribute | Behavior |
|---|---|
label |
Renders a <label> for the select. Changing it updates the label in place; removing it removes the label. |
name, disabled, required, autocomplete, form |
Copied to the inner select and kept on the host. |
id |
Moved to the inner select and removed from the host. A generated id is used when absent. |
aria-* |
Moved to the inner select and removed from the host. |
multiple and size are not supported (listbox mode is only
styleable in Chromium). Setting or removing id or an aria-*
attribute on the host after upgrade updates the inner select, so a
framework can toggle aria-invalid or aria-describedby for error
messages. Removing id falls back to the generated id.
At first render every aria-* attribute moves. After that, a newly set
aria-* attribute moves only if it is listed in the exported
ARIA_ATTRIBUTES array. Removing any aria-* attribute from the host
removes it from the select.
Authored <option> and <optgroup> children are moved into the select
on first connect, and options appended to the host later are moved to
the end of the select. Other children present at first connect are
dropped; non-option children appended later are left in place.
A framework that later inserts a node relative to a moved option may
fail, because that option is no longer a child of the host. Manage
dynamic option lists through el.select.
value-- read or write the selected value. A value set before the element renders is held until an option with that value exists, whether it is appended to the host or added throughel.select, then selected, unless a latervalueset or a user pick replaces it. Before render,valuereturns the waiting value. Once rendered, the select starts with no selection while the value waits (valueis""), even if an option was authoredselected; options added after that follow the browser's usual selection rules. Options appended to the host in the same tick are moved in before a new value is applied. After render, setting a value with no matching option leaves"".select-- the innerHTMLSelectElement, ornullbefore the first render.label,name,disabled,required-- reflect the attributes of the same name.
Native change and input events bubble from the inner select
unchanged. On change the element also emits substrate-select:change
with detail: { value:string } (SubstrateSelectChangeDetail).
el.addEventListener(SubstrateSelect.event('change'), ev => {
console.log(ev.detail.value)
})
// or
el.on('change', ev => console.log(ev.detail.value))Setting el.value from code fires neither event, like a native select.
The select is a light-DOM descendant of the enclosing <form>, so
submission and FormData include it with no extra work.
import '@substrate-system/select/css'Or minified:
import '@substrate-system/select/min/css'The first eight tokens fall back to a shared --substrate-* variable,
then to a default. The last three have only a default.
| Token | Falls back to | Default |
|---|---|---|
--substrate-select-text |
--substrate-text |
black |
--substrate-select-surface |
--substrate-surface |
white |
--substrate-select-border |
--substrate-border |
#9b9b9b |
--substrate-select-accent |
--substrate-accent |
#2563eb |
--substrate-select-focus |
--substrate-focus |
#2563eb |
--substrate-select-focus-width |
--substrate-focus-width |
2px |
--substrate-select-focus-offset |
--substrate-focus-offset |
2px |
--substrate-select-radius |
--substrate-radius |
0 |
--substrate-select-option-hover |
none | #f3f4f6 |
--substrate-select-checked |
none | #1d4ed8 |
--substrate-select-shadow |
none | 0 4px 12px #21212114 |
--substrate-select-checked colors the chosen option's text in the
picker. It does not follow the accent, so set it too when you change
the accent (--substrate-select-accent or --substrate-accent).
substrate-select {
--substrate-select-accent: rebeccapurple;
--substrate-select-checked: rebeccapurple;
}The baseline (outlined trigger, chevron, focus and hover states) works
in every browser. Where appearance: base-select is supported, the
picker is styled too: a rotating chevron, a checkmark on the chosen
option, and an open transition, which respects reduced motion. Today
that is Chromium (Chrome and Edge 135+). Safari 27 support is announced
but unconfirmed in stable, and Firefox has it only behind flags.
Elsewhere the browser's native picker opens.
The stylesheet hides substrate-select until the browser has defined
it, so you do not see unstyled markup while the JS loads.
That only covers this one element. If your page uses several custom elements, hide the whole page until they are all ready, and reveal it once:
<html class="reduce-fouce">html.reduce-fouce { opacity: 0; }await Promise.race([
Promise.allSettled([
customElements.whenDefined('substrate-select')
]),
// reveal anyway after two seconds
new Promise(resolve => { setTimeout(resolve, 2000) })
])
document.documentElement.classList.remove('reduce-fouce')Keep the timeout, and add a <noscript> override. Without both, a
component that fails to define leaves the page blank:
<noscript>
<style>html.reduce-fouce { opacity: 1 !important; }</style>
</noscript>This calls the global function customElements.define. Just import, then use
the tag in your HTML.
import '@substrate-system/select'<substrate-select label="Size" name="size">
<option value="s">Small</option>
<option value="l">Large</option>
</substrate-select>This package exposes minified JS and CSS files too. Copy them to a location that is accessible to your web server, then link to them in HTML.
cp ./node_modules/@substrate-system/select/dist/index.min.js ./public/substrate-select.min.js
cp ./node_modules/@substrate-system/select/dist/index.min.css ./public/substrate-select.css<head>
<link rel="stylesheet" href="./substrate-select.css">
</head>
<body>
<!-- ... -->
<script type="module" src="./substrate-select.min.js"></script>
</body>