Selector
pivot-selector is a single-select form control built on the native <select> element (using the customizable-select appearance: base-select API), with Pivot field labeling, helper/error messaging, and form association through ElementInternals.
Quick Start
<!-- Basic usage -->
<pivot-selector
pivot-name="fruit"
pivot-label="Favorite fruit"
pivot-options='[{"label":"Apple","value":"apple"},{"label":"Banana","value":"banana"}]'
></pivot-selector>
<!-- Required, with helper text and a pre-selected value -->
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-required
pivot-helper-text="We use this to show relevant offers"
pivot-value="us"
pivot-options='[{"label":"United States","value":"us"},{"label":"Canada","value":"ca"}]'
></pivot-selector>Using the field-label-tooltip slot
Place a pivot-field-label-tooltip in the field-label-tooltip slot to add an info icon next to the field label. Activating the icon opens a popover with supplemental context for the field — the tooltip’s own header comes from its pivot-tooltip-popover-header attribute, and its body content goes inside it as child elements.
<pivot-selector
pivot-name="routing-number"
pivot-label="Routing number"
pivot-options='[{"label":"Checking","value":"checking"},{"label":"Savings","value":"savings"}]'
>
<pivot-field-label-tooltip
slot="field-label-tooltip"
pivot-tooltip-popover-header="What is a routing number?"
>
<pivot-text>
Your 9-digit routing number is printed at the bottom-left of your personal
check.
</pivot-text>
</pivot-field-label-tooltip>
</pivot-selector>Use this slot for supplemental, non-essential context — information that helps some users but isn’t required to complete the field. If the content is critical to completing the field, use pivot-helper-text instead.
The slot="field-label-tooltip" attribute is required — a <pivot-field-label-tooltip> child without it is not rendered, and the component logs a console warning naming the element.
See the pivot-field-label-tooltip documentation for full usage guidelines.
Using the pivot-selector-change event
pivot-selector fires pivot-selector-change whenever the selected option changes — in addition to updating its own pivotValue property and the underlying <select>'s form value. The event detail carries the new value.
<pivot-selector
id="country-selector"
pivot-name="country"
pivot-label="Country"
pivot-options='[{"label":"United States","value":"us"},{"label":"Canada","value":"ca"},{"label":"Mexico","value":"mx"}]'
></pivot-selector>
<script>
document
.getElementById("country-selector")
.addEventListener("pivot-selector-change", (event) => {
console.log(event.detail.value); // e.g. "ca"
});
</script>The event bubbles and is composed, so it can also be caught by a listener on an ancestor outside the component’s shadow root, not just one bound directly to the element.
CSS Parts
| Name | Description |
|---|---|
container |
The component’s outer wrapper div. |
Form Association
pivot-selector is form-associated via ElementInternals (static formAssociated = true), so it behaves like a native form control without extra wiring:
- Its value is submitted under
pivot-namewhen placed inside a<form>. - Validity (including “value missing” for a required-but-unset field) is read from the live
<select>and reported through the internals, so native constraint validation and:invalidstyling work as expected. formResetCallbackrestores the value the component had on first render, not""— resetting the form returns the field to its initial selection and clears any native validation message currently displayed.formDisabledCallbackdisables the control automatically when a containing<fieldset disabled>or the form itself is disabled.pivot-selectordefines its owncheckValidity()/reportValidity()methods, so you can validate the element directly without going through the containing form. Both also propagate into the parent form’s validity state.
Validation and Error Display
pivot-selector intercepts the browser’s invalid event and calls preventDefault() on it, so the browser’s native validation bubble never appears. Instead, the <select>'s validationMessage is rendered below the field by pivot-field-helper-message, using the same error icon and styling as pivot-error-text. This happens whenever an invalid event fires for the field — on a blocked form submission, on form.checkValidity() / form.reportValidity(), or on the element’s own checkValidity() / reportValidity().
<form>
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-required
pivot-options='[{"label":"United States","value":"us"},{"label":"Canada","value":"ca"}]'
></pivot-selector>
<button type="submit">Submit</button>
</form>
<!-- Submitting without choosing an option renders the browser's
required-field message below the field in Pivot error styling. -->The message is removed as soon as the field becomes valid again (i.e. an option is selected) and when the parent form is reset.
The field is in its error state — error styling, aria-invalid="true", and a has-error attribute on the host — when pivot-error is set, pivot-error-text has a value, or a native validation message is displayed. When both pivot-error-text and a native validation message are present, pivot-error-text is the message shown. Setting pivot-error alone applies the error styling without a message, and any pivot-helper-text stays visible. The component manages has-error itself; don’t set or remove it manually.
pivot-error and pivot-error-text do not affect the element’s validity — use them to display errors from your own (e.g. server-side) validation.
Methods
checkValidity()
Returns boolean. Checks the current constraint-validation state of the native <select> (kept in sync with ElementInternals after every update) and returns whether it is currently valid. When the field is invalid, the browser fires an invalid event on the host, and the validation message is rendered inline below the field — see Validation and Error Display.
const selector = document.querySelector("pivot-selector[pivot-name='country']");
selector.checkValidity(); // true | falsereportValidity()
Returns boolean. Performs the same validity check as checkValidity(). The browser’s native validation bubble is suppressed; when the field is invalid, the validation message is rendered inline below the field instead, exactly as with checkValidity().
const selector = document.querySelector("pivot-selector[pivot-name='country']");
selector.reportValidity(); // renders the validation message inline if invalidBoth methods reflect the same validity state that the containing form’s checkValidity() / reportValidity() aggregate — see Form Association.
Options Are Rendered Internally, Not Slotted
pivot-options is the only supported way to supply choices — pivot-selector does not accept slotted <option> elements.
<!-- ✅ Supply options via pivot-options -->
<pivot-selector
pivot-name="size"
pivot-options='[{"label":"Small","value":"sm"},{"label":"Large","value":"lg"}]'
></pivot-selector>
<!-- ❌ Slotted options render but are not selectable -->
<pivot-selector pivot-name="size">
<option value="sm">Small</option>
<option value="lg">Large</option>
</pivot-selector>This isn’t a style preference: Chromium’s customizable-select implementation (appearance: base-select) doesn’t add slotted light-DOM <option> elements to a shadow-hosted <select>'s option list — it renders their text but never makes them selectable. Options have to be rendered declaratively inside the component’s own shadow root, which is what pivot-options drives.
Each entry in pivot-options is { label, value, disabled? } — label is the visible text, value is what’s submitted with the form when the option is selected, and the optional disabled field renders that individual option as unselectable (and without its checkmark) while leaving the rest of the list interactive:
<pivot-selector
pivot-name="plan"
pivot-label="Plan"
pivot-options='[
{"label":"Free","value":"free"},
{"label":"Pro","value":"pro"},
{"label":"Enterprise (contact sales)","value":"enterprise","disabled":true}
]'
></pivot-selector>Accessibility
pivot-selector wraps a native <select>, so most select semantics and keyboard behavior come from the browser for free — the component’s job is to keep labeling, validity, and error messaging in sync with it.
Screen Reader Behavior
pivot-selector renders its <label> (via the shared renderFieldLabel helper) directly inside its own shadow root, in the same template as the <select>. The label’s for and the select’s id (the same generated or pivot-id-supplied string) form a genuine native label association per the HTML label-association algorithm.
On top of that native association, the select’s accessible name is also set explicitly via aria-label: pivot-aria-label if provided, otherwise it falls back to the visible pivot-label text automatically (WCAG 4.1.2). Because an explicit aria-label takes precedence over an associated <label> in accessible-name computation, this guarantees a correct accessible name even in the one case where no <label> element is rendered at all — when pivot-label is omitted — so in the common case (a visible pivot-label), you don’t need to set pivot-aria-label at all.
Set pivot-aria-label when you need the accessible name to differ from the visible label, most commonly when pivot-label is omitted entirely and there is no visible text to fall back to. pivot-aria-label is applied unconditionally whenever it has a value, taking precedence over the pivot-label fallback — avoid setting it to different text than pivot-label when both are present, since that produces a mismatch between the visible label and the accessible name (WCAG 2.5.3, Label in Name).
aria-invalid reflects the field’s error state (pivot-error, pivot-error-text, or a displayed native validation message), and aria-describedby points at the helper/error message region whenever helper text, pivot-error-text, or a native validation message is present, so assistive technology announces the current guidance or error alongside the field. Because error messages render with role="alert" in pivot-field-helper-message, a native validation message is also announced as soon as it appears after a failed submit. The required state is exposed through the native required attribute (set via pivot-required), not just the visual *, so it’s announced as required by screen readers, not only shown visually.
Keyboard Navigation
Keyboard interaction is entirely native <select> behavior — pivot-selector doesn’t add or override any key handling: Tab/Shift+Tab moves focus to and from the control, Space/Enter/arrow keys open the listbox and move the active option, and Escape closes it without changing the selection.
Focus Management
pivot-selector does not manage focus itself; it relies on the native <select>'s own focus behavior, including the browser’s :focus-visible outline (styled with an offset in selector.css).
When form submission or reportValidity() fails, focus is not moved to the field — the component cancels the invalid event to suppress the native bubble, which also cancels the browser’s built-in focus-on-invalid behavior. If you want the first invalid field focused on submit, handle it in your own code — for example, listen for invalid on the form in the capture phase (the event does not bubble) and call .focus() on the first host that fires it. The rendered error message is still announced via role="alert" (WCAG 3.3.1).
Related Components
- Field Helper Message — renders this component’s helper/error text region internally.
- Field Label Tooltip — the supported component for the
field-label-tooltipslot.
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-label |
string |
"" |
This will create an attribute: pivot-label="value" |
pivot-aria-label |
string |
"" |
The accessible name for the select. `renderFieldLabel` renders the `<label>` directly inside this component's own shadow root, alongside the `<select>`, so a real native `for`/`id` association exists between them (unlike the pre-refactor `pivot-field-label` custom element, which rendered its `<label>` in a separate shadow root that `for`/`id` association could not reach). That native association still doesn't decide the announced name, though: `aria-label` takes precedence over an associated `<label>` in accessible-name computation, and the select's `aria-label` falls back to `pivotLabel` automatically when this is unset — so this only needs to be set to override that text (e.g. when the accessible name should differ from the visible label, or when `pivotLabel` is omitted entirely). |
pivot-helper-text |
string | null |
null |
This will create an attribute: pivot-helper-text="value" |
pivot-error-text |
string | null |
null |
This will create an attribute: pivot-error-text="value" |
pivot-name |
string |
"" |
This will create an attribute: pivot-name="value" |
pivot-id |
string |
"" |
This will create an attribute: pivot-id="value" |
pivot-value |
string |
"" |
The value of the currently selected option. Set this to pre-select an option on first render. |
pivot-options |
SelectorOption[] |
[] |
Array of options to render inside the `<select>`. Each item must supply at least `label` and `value`. Can be set as a JSON string attribute or as a JavaScript property. |
pivot-optional |
boolean |
false |
Presence of attribute means true: <pivot-input pivot-optional> |
pivot-required |
boolean |
false |
Presence of attribute means true: <pivot-input pivot-required> |
pivot-error |
boolean |
false |
Presence of attribute means true: <pivot-input pivot-error> |
pivot-disabled |
boolean |
false |
Presence of attribute means true: <pivot-input pivot-disabled> |
Slots
| Name | Description |
|---|---|
field-label-tooltip |
Optional tooltip content rendered beside the field label |
Events
| Name | Type | Description |
|---|---|---|
pivot-selector-change |
CustomEvent |
Fired when the selected option changes. Detail: `{ value: string }` |
CSS Custom Properties
| Name | Description |
|---|---|
--component-field-gap |
Gap between the label row and the select, and margin above the options popover. |
--component-field-label-gap |
Gap between the label text and its optional/required indicator or tooltip icon. |
--component-field-label-color |
Text color of the label. |
--global-color-text-on-light-light-color |
Text color of the "(optional)" indicator. |
--global-color-text-on-light-error-color |
Text color of the required "*" indicator. |
--global-interaction-md |
Minimum block size of the select control and of each option. |
--typography-constants-body-family |
Font family for the select, its selected-value button, each option, the label, and the "(optional)" indicator. |
--typography-body-md-size |
Font size for the select, its selected-value button, each option, the label, and the "(optional)" indicator. |
--typography-body-md-height |
Line height for the select, its selected-value button, each option, the label, and the "(optional)" indicator. |
--global-color-text-on-light-dark-color |
Text color of the selected-value button and each option. |
--typography-icon-md-size |
Size of the dropdown chevron icon. |
--global-color-icons-font-awesome-default-color |
Color of the dropdown chevron icon. |
--component-field-control-selector-popover-surface |
Background color of the options popover. |
--global-radius-sm |
Corner radius of the options popover. |
--global-elevation-shadow1-x |
Horizontal offset of the options popover's shadow. |
--global-elevation-shadow1-y |
Vertical offset of the options popover's shadow. |
--global-elevation-shadow1-blur |
Blur radius of the options popover's shadow. |
--global-elevation-shadow1-spread |
Spread of the options popover's shadow. |
--global-elevation-shadow1-fill |
Color of the options popover's shadow. |
--typography-constants-icon-family |
Font family for the option checkmark icon. |
--global-color-icons-font-awesome-primary-color |
Color of the option checkmark icon. |
--typography-icon-md-height |
Minimum inline size reserved for the option checkmark icon. |
--component-field-control-selector-object-surface-hover |
Background color of an option on hover. |
--component-field-control-general-inset-x |
Padding of each option. |
--component-field-control-general-gap |
Gap between elements within an option. |
--component-field-control-input-placeholder |
Text color of the selected-value button when no option is selected. |
Basic selector
<pivot-selector
pivot-name="fruit"
pivot-label="Favorite fruit"
pivot-options='[
{ "label": "Apple", "value": "apple" },
{ "label": "Banana", "value": "banana" },
{ "label": "Cherry", "value": "cherry" }
]'
></pivot-selector>Pre-selected option (pivot-value)
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-value="ca"
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>Individual disabled option (option.disabled)
Set disabled: true on an item in pivot-options to make that specific choice visible in the list but unselectable, while the rest of the field stays interactive.
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx", "disabled": true }
]'
></pivot-selector>Required (pivot-required)
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-required
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>Optional (pivot-optional)
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-optional
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>No visible label (pivot-aria-label)
If pivot-label is omitted, set pivot-aria-label instead so the control still has an accessible name.
<pivot-selector
pivot-name="fruit"
pivot-aria-label="Favorite fruit"
pivot-options='[
{ "label": "Apple", "value": "apple" },
{ "label": "Banana", "value": "banana" },
{ "label": "Cherry", "value": "cherry" }
]'
></pivot-selector>Field label tooltip (pivot-field-label-tooltip)
Use a tooltip to surface supplemental context about the field — information that helps some users but isn't required to complete it. If the content is critical to completing the field, use pivot-helper-text instead.
<pivot-selector
pivot-name="routing-number"
pivot-label="Routing number"
pivot-options='[
{ "label": "Checking", "value": "checking" },
{ "label": "Savings", "value": "savings" }
]'
>
<pivot-field-label-tooltip
slot="field-label-tooltip"
pivot-tooltip-popover-header="What is a routing number?"
>
<pivot-text>
Your 9-digit routing number is printed at the bottom-left of your personal
check.
</pivot-text>
</pivot-field-label-tooltip>
</pivot-selector>Helper text (pivot-helper-text)
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-helper-text="We use this to show relevant offers."
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>Error state (pivot-error + pivot-error-text)
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-error
pivot-error-text="Please select a country to continue."
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>Error text replaces helper text (both set, error active)
<!-- When pivot-error is active, error text replaces helper text -->
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-error
pivot-error-text="Please select a country to continue."
pivot-helper-text="We use this to show relevant offers."
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>Disabled (pivot-disabled)
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-disabled
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>Disabled with pre-selected option
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-disabled
pivot-value="us"
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>Options set via JavaScript property
<pivot-selector
id="channel-selector"
pivot-name="channel"
pivot-label="Preferred channel"
></pivot-selector>
<script>
const selector = document.getElementById("channel-selector");
selector.pivotOptions = [
{ label: "Email", value: "email" },
{ label: "SMS", value: "sms" },
{ label: "Push", value: "push" },
{ label: "In-app", value: "in-app" },
];
selector.pivotValue = "push";
</script>Event: pivot-selector-change
<pivot-selector
id="my-selector"
pivot-name="country"
pivot-label="Country"
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>
<script>
document
.getElementById("my-selector")
.addEventListener("pivot-selector-change", (e) => {
console.log(e.detail.value); // e.g. "ca"
});
</script>Full form example
<pivot-form-container>
<pivot-input
pivot-name="full-name"
pivot-label="Full name"
pivot-type="text"
pivot-required
></pivot-input>
<pivot-selector
pivot-name="country"
pivot-label="Country"
pivot-required
pivot-helper-text="We use this to show relevant offers."
pivot-options='[
{ "label": "United States", "value": "us" },
{ "label": "Canada", "value": "ca" },
{ "label": "Mexico", "value": "mx" }
]'
></pivot-selector>
<pivot-button pivot-type="submit">Submit</pivot-button>
<pivot-button pivot-variant="secondary" pivot-type="reset"
>Reset</pivot-button
>
</pivot-form-container>