Pivot Docs

    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-name when 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 :invalid styling work as expected.
    • formResetCallback restores 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.
    • formDisabledCallback disables the control automatically when a containing <fieldset disabled> or the form itself is disabled.
    • pivot-selector defines its own checkValidity() / 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 | false

    reportValidity()

    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 invalid

    Both 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


    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.