Pivot Docs

    Radio

    pivot-radio is a radio group web component that renders a labelled <fieldset> containing one or more <input type="radio"> / <label> pairs. Options are driven entirely by the pivot-options property. The component uses native HTML form controls throughout, so browser constraint validation, accessibility semantics, and keyboard behavior are all handled by the platform.


    Quick Start

    <!-- Basic radio group -->
    <pivot-radio
    pivot-fieldset-label="Preferred contact method"
    pivot-name="contact"
    pivot-options='[
    { "label": "Email", "value": "email" },
    { "label": "Phone", "value": "phone" },
    { "label": "Mail", "value": "mail" }
    ]'

    >
    </pivot-radio>

    <!-- Pre-selected option -->
    <pivot-radio
    pivot-fieldset-label="Preferred contact method"
    pivot-name="contact"
    pivot-value="phone"
    pivot-options='[
    { "label": "Email", "value": "email" },
    { "label": "Phone", "value": "phone" },
    { "label": "Mail", "value": "mail" }
    ]'

    >
    </pivot-radio>

    <!-- Required with helper text -->
    <pivot-radio
    pivot-fieldset-label="Preferred contact method"
    pivot-name="contact"
    pivot-required
    pivot-helper-text="Select one option to continue"
    pivot-options='[
    { "label": "Email", "value": "email" },
    { "label": "Phone", "value": "phone" }
    ]'

    >
    </pivot-radio>

    <!-- Error state -->
    <pivot-radio
    pivot-fieldset-label="Preferred contact method"
    pivot-name="contact"
    pivot-error
    pivot-error-text="Please select an option"
    pivot-options='[
    { "label": "Email", "value": "email" },
    { "label": "Phone", "value": "phone" }
    ]'

    >
    </pivot-radio>

    Using the field-label-tooltip slot

    The field-label-tooltip slot accepts a single pivot-field-label-tooltip element. When present, pivot-radio renders it inline with the fieldset legend so an info-icon button appears beside the group label. See the pivot-field-label-tooltip documentation for the tooltip’s own usage rules.

    <pivot-radio
    pivot-fieldset-label="Preferred contact method"
    pivot-name="contact"
    pivot-options='[{ "label": "Email", "value": "email" }]'
    >

    <pivot-field-label-tooltip
    slot="field-label-tooltip"
    pivot-tooltip-popover-header="Why do we ask?"
    >

    <pivot-text> We use this to personalize your experience. </pivot-text>
    </pivot-field-label-tooltip>
    </pivot-radio>

    pivot-radio tracks whether this slot has assigned content itself: before every render it checks its own children for one with slot="field-label-tooltip" and stores the result in its internal hasFieldLabelTooltip state. That flag is passed straight into the shared renderFieldLabel() helper, which pivot-radio calls directly inside its own <legend>. When hasFieldLabelTooltip is true, renderFieldLabel() renders a wrapper <div class="field-label-tooltip"> containing a <slot name="field-label-tooltip"> in pivot-radio’s own shadow root, which is what projects your <pivot-field-label-tooltip> element next to the group label. 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.


    Using the pivot-radio-change event

    pivot-radio-change fires once per selection change — on the native change event of whichever <input type="radio"> the user just checked. It does not fire when pivot-value is set programmatically or pre-selects an option on first render. The event bubbles and is composed, so it can be listened for from outside the component’s shadow DOM at any ancestor:

    document
    .querySelector("pivot-radio")
    .addEventListener("pivot-radio-change", (event) => {
    console.log(event.detail.value); // e.g. "email" — the newly selected option's value
    });

    event.detail is always { value: string }, where value matches the value field of the option the user just selected. pivot-radio also updates its own pivotValue property in the same tick, so reading radio.pivotValue after the event fires returns the same value.


    Form Association

    pivot-radio sets static formAssociated = true, making it a form-associated custom element. This means:

    • The selected value is included in FormData when the parent form is submitted, using pivot-name as the key.
    • pivot-radio 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, since the group’s validity is forwarded to ElementInternals via setValidity() after every update.
    • Form reset via <button type="reset"> or form.reset() restores pivotValue to the state it had at first render and clears any native validation message currently displayed.
    • When a parent <fieldset> or form is disabled, the component disables itself via formDisabledCallback.

    name attribute

    Each generated <input type="radio"> carries name="${pivotName}" so the browser’s native radio-grouping (single-selection enforcement, arrow-key navigation) works within the shadow root. Separately, pivot-radio also mirrors pivot-name onto the host element’s own native name attribute on every update. This host-level attribute is required by the form-associated custom elements spec so the browser uses the correct key when building FormData from ElementInternals.setFormValue() — it serves a different purpose than the name attribute on the individual radio inputs. Do not manually set a name attribute on the host element — it will be overwritten.

    Required validation

    When pivot-required is set and no option is selected, the component reports valueMissing: true via ElementInternals with the message “Please select an option.” This prevents form submission, and the message is rendered below the group (see Validation and Error Display). The native required attribute is not set on the individual <input> elements — group-level validation is handled entirely through ElementInternals.


    Validation and Error Display

    pivot-radio intercepts the browser’s invalid event and calls preventDefault() on it, so the browser’s native validation bubble never appears. Instead, the group’s validation message is rendered below the options 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 group — on a blocked form submission, on form.checkValidity() / form.reportValidity(), or on the element’s own checkValidity() / reportValidity().

    <form>
    <pivot-radio
    pivot-fieldset-label="Preferred contact method"
    pivot-name="contact"
    pivot-required
    pivot-options='[{ "label": "Email", "value": "email" }, { "label": "Phone", "value": "phone" }]'
    >
    </pivot-radio>
    <button type="submit">Submit</button>
    </form>
    <!-- Submitting with no selection renders "Please select an option."
    below the group in Pivot error styling. -->

    The message is removed as soon as the group becomes valid again (i.e. an option is selected) and when the parent form is reset.

    The group is in its error state — error styling on every option, 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. The component manages has-error itself; don’t set or remove it manually.

    pivot-error and pivot-error-text do not affect the group’s validity — use them to display errors from your own (e.g. server-side) validation.


    Methods

    checkValidity()

    Returns boolean. Checks the group’s current constraint-validation state (kept in sync with ElementInternals after every update — see Form Association) and returns whether it is currently valid. When the group is invalid, the browser fires an invalid event on the host, and the validation message is rendered inline below the group — see Validation and Error Display.

    const radio = document.querySelector("pivot-radio[pivot-name='contact']");
    radio.checkValidity(); // true | false

    reportValidity()

    Returns boolean. Performs the same validity check as checkValidity(). The browser’s native validation bubble is suppressed; when the group is invalid, the validation message is rendered inline below the group instead, exactly as with checkValidity().

    const radio = document.querySelector("pivot-radio[pivot-name='contact']");
    radio.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.


    CSS Parts

    Part Element Description
    fieldset <fieldset> The wrapping fieldset element
    legend <legend> The fieldset legend (group label)
    option <div> wrapping each input/label pair Container for one radio option row
    input <input type="radio"> Each radio input element
    label <label> Each option’s label element

    The pivot-options Property

    pivot-options drives every option pivot-radio renders. It can be set as a JSON string attribute (as shown in Quick Start) or as a JavaScript property:

    const radio = document.querySelector("pivot-radio");
    radio.pivotOptions = [
    { label: "Email", value: "email" },
    { label: "Phone", value: "phone" },
    ];

    Each item in the array must satisfy the RadioOption shape:

    interface RadioOption {
    label: string; // Display text rendered next to the input
    value: string; // Value submitted/matched for selection state
    showInputField?: boolean | string; // When truthy, renders a pivot-input below this option's label
    showTextAreaField?: boolean | string; // When truthy, renders a pivot-text-area below this option's label
    showDateField?: boolean | string; // When truthy, renders a pivot-date below this option's label
    placeholder?: string; // Placeholder text for the accompanying pivot-input or pivot-text-area, if either is set
    maxLength?: number; // Character limit passed to the accompanying pivot-text-area, if showTextAreaField is set
    textAreaRows?: number; // Row count passed to the accompanying pivot-text-area, if showTextAreaField is set
    minDate?: string; // Earliest selectable date passed to the accompanying pivot-date, if showDateField is set
    maxDate?: string; // Latest selectable date passed to the accompanying pivot-date, if showDateField is set
    step?: string; // Step interval (in days) passed to the accompanying pivot-date, if showDateField is set
    }

    Set exactly one of showInputField, showTextAreaField, or showDateField (truthy — true or any non-empty string) to render a companion form control below that option’s label:

    • showInputField renders a pivot-input. Use placeholder to provide a format hint inside the input.
    • showTextAreaField renders a pivot-text-area. Use placeholder for a format hint, maxLength to cap and display a character count, and textAreaRows to control its visible height (defaults to 4 if unset).
    • showDateField renders a pivot-date. Use minDate / maxDate (in YYYY-MM-DD format) to bound the selectable range, and step to set the picker’s step interval in days.

    Every companion control inherits the group’s pivot-name, pivot-error, and pivot-disabled states, and uses the option’s label as its accessible name. When the group is pivot-required, a companion is required only while its option is selected.

    When its option is selected, a companion’s non-empty value is submitted as <pivot-name>-<option value> (e.g. animal=other&animal-other=…). An invalid companion (e.g. required and empty) makes the group invalid and blocks form submission.

    Note: Only place one of showInputField, showTextAreaField, or showDateField on the last option in the array. The grid layout positions the companion field after the option row and is not designed to accommodate options that follow it.


    Implementation Notes

    • pivot-name is required for correct single-selection behavior. All generated <input type="radio"> elements share this name. Without it, the browser cannot group them and multiple options could be checked simultaneously.
    • pivot-value pre-selects an option by matching against each option’s value. Set it in markup or via JS before or after render. When the user changes selection, pivot-value is updated automatically and a pivot-radio-change event is fired.
    • Helper and error text rendering is delegated to pivot-field-helper-message. The message region is only rendered when there is helper text, pivot-error-text, or a native validation message to show; otherwise the region is omitted entirely. See the pivot-field-helper-message documentation for details on its rendering logic.
    • Error text replaces pivot-helper-text while it is shown. Setting pivot-error-text on its own is enough to show the error icon, message, and error styling. Setting pivot-error alone applies error styling to the options without a message, and helper text stays visible. See Validation and Error Display for how native validation messages fit in.

    Accessibility

    pivot-radio is built entirely from native HTML form elements — <fieldset>, <legend>, <input type="radio">, and <label> — so the browser and assistive technology handle the core accessible semantics with no custom ARIA role of its own. The component layers in two state-driven attributes on top of that native foundation:

    • aria-invalid — set to "true" on every <input type="radio"> in the group whenever the group is in its error state (pivot-error, pivot-error-text, or a displayed native validation message), otherwise "false" (WCAG 4.1.2).
    • aria-describedby — when helper text, pivot-error-text, or a native validation message is present, each radio input is linked to the rendered pivot-field-helper-message via aria-describedby, so assistive technology announces the helper or error message when any option in the group receives focus (WCAG 1.3.1, 4.1.3). The error text is additionally announced immediately via pivot-field-helper-message’s own role="alert", not only when an option regains focus — see that component’s README.

    ARIA Roles and Attributes

    Element Implicit role Notes
    <fieldset> group Groups all radio inputs under a common label
    <legend> — Labels the <fieldset> group; announced when focus enters the group
    <input type="radio"> radio Carries aria-checked state managed by the browser
    <label> — Associated to each input via for / id; expands the clickable hit area

    Not currently set by the component: aria-errormessage.

    Per the WAI-ARIA Authoring Practices Guide, descriptive group text is conventionally associated via aria-describedby on the <fieldset> rather than on each input; this component associates it per-input instead, which still reaches assistive technology as focus moves to any radio in the group.

    Screen Reader Behavior

    • When focus enters a radio input, screen readers announce the input’s checked state, the associated label text, and the group name (from the <legend>).
    • Navigating between options with arrow keys causes each option’s label to be announced as focus moves.
    • The helper or error message — including a native validation message rendered after a failed submit — is associated with each radio input via aria-describedby, so screen readers announce it as focus moves to any option in the group. Because error messages render with role="alert", a native validation message is also announced as soon as it appears.

    Keyboard Navigation

    pivot-radio attaches no keyboard handlers of its own — it inherits all standard keyboard behavior from native <input type="radio"> elements that share a name:

    Key Behavior
    Tab Moves focus into the radio group. If an option is checked, focus lands on it; otherwise on the first option.
    Shift + Tab Moves focus out of the radio group to the previous focusable element.
    Arrow Right / Arrow Down Moves focus to the next option, checks it, and unchecks the previous one. Wraps to first.
    Arrow Left / Arrow Up Moves focus to the previous option, checks it, and unchecks the previous one. Wraps to last.
    Space Checks the focused option if it is not already checked.

    This matches the WAI-ARIA Authoring Practices Guide radio group keyboard pattern (WCAG 2.1.1).

    Focus Management

    • Focus is fully browser-managed through native radio inputs; the component does not manually manage tabindex or override focus behavior for the options themselves.
    • The component relies on the browser’s native focus-visible rendering for radio inputs.
    • pivot-radio sets delegatesFocus: true via PivotBase’s shadow root options, so calling .focus() on the host element delegates focus to the first focusable element inside its shadow DOM.
    • When form submission or reportValidity() fails, focus is not moved to the group — 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 the helper/error text region below the options.
    • Field Label Tooltip — the component accepted by the field-label-tooltip slot.
    • Input — rendered as a companion control when an option sets showInputField.
    • Text Area — rendered as a companion control when an option sets showTextAreaField.
    • Date — rendered as a companion control when an option sets showDateField.
    • Form Container

    References


    API Reference

    Props

    Name Type Default Description
    pivot-fieldset-label string "" Label text rendered inside the `<legend>` element.
    pivot-optional boolean false Presence of attribute means true: <pivot-input pivot-optional>
    pivot-name string "" The `name` attribute shared by all radio inputs in the group. Required for correct single-selection behaviour.
    pivot-value string "" The `value` of the currently selected radio option. Set this to pre-select an option on first render.
    pivot-error boolean false Presence of attribute means true: <pivot-radio pivot-error>
    pivot-required boolean false When true, all radio inputs in the group are required.
    pivot-disabled boolean false When true, all radio inputs in the group are disabled.
    pivot-error-text string | null null This will create an attribute: pivot-error-text="value"
    pivot-helper-text string | null null This will create an attribute: pivot-helper-text="value"
    pivot-options RadioOption[] [] Array of radio options to render inside the fieldset. Each item must supply at least `label` and `value`. Can be set as a JSON string attribute or as a JavaScript property.

    Slots

    Name Description
    field-label-tooltip Optional tooltip content rendered beside the fieldset label

    Events

    Name Type Description
    pivot-radio-change CustomEvent Fired when the selected option changes. Detail shape: `{ value: string }`.

    CSS Custom Properties

    Name Description
    --component-field-control-radio-inset-y Vertical padding used around each radio control and label.
    --component-field-label-gap Horizontal spacing between each radio input and its label.
    --component-field-control-general-gap Additional inline offset added to the control size when aligning a companion field (pivot-input/pivot-date/pivot-text-area) under an option's label.
    --typography-icon-md-size Size of each radio input control.
    --typography-body-md-size Font size for radio option labels.
    --typography-body-md-height Line height for radio option labels.
    --global-color-icons-font-awesome-primary-color Accent color for radio inputs in the default state.
    --global-color-icons-font-awesome-danger-color Accent and icon color used in the error state.
    --global-color-icons-font-awesome-disabled-color Accent color used for disabled radio inputs.
    --global-color-text-on-light-error-color Option label color used in the error state. Helper and error message text colors are handled by `pivot-field-helper-message`.
    --component-input-field-input-disabled Label color used when the group is disabled.