Pivot Docs

    Checkbox

    pivot-checkbox is a checkbox group web component that renders a labelled <fieldset> containing one or more <input type="checkbox"> / <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 checkbox group -->
    <pivot-checkbox
    pivot-fieldset-label="Areas of interest"
    pivot-name="interest"
    pivot-options='[
    { "label": "Design", "value": "design" },
    { "label": "Engineering", "value": "engineering" },
    { "label": "Research", "value": "research" }
    ]'

    >
    </pivot-checkbox>

    <!-- Pre-selected options (multiple) -->
    <pivot-checkbox
    pivot-fieldset-label="Areas of interest"
    pivot-name="interest"
    pivot-value='["design", "research"]'
    pivot-options='[
    { "label": "Design", "value": "design" },
    { "label": "Engineering", "value": "engineering" },
    { "label": "Research", "value": "research" }
    ]'

    >
    </pivot-checkbox>

    <!-- Pre-selected option (single — plain string is also accepted) -->
    <pivot-checkbox
    pivot-fieldset-label="Areas of interest"
    pivot-name="interest"
    pivot-value="design"
    pivot-options='[
    { "label": "Design", "value": "design" },
    { "label": "Engineering", "value": "engineering" },
    { "label": "Research", "value": "research" }
    ]'

    >
    </pivot-checkbox>

    <!-- Required with helper text -->
    <pivot-checkbox
    pivot-fieldset-label="Areas of interest"
    pivot-name="interest"
    pivot-required
    pivot-helper-text="Select at least one option to continue"
    pivot-options='[
    { "label": "Design", "value": "design" },
    { "label": "Engineering", "value": "engineering" }
    ]'

    >
    </pivot-checkbox>

    <!-- Error state -->
    <pivot-checkbox
    pivot-fieldset-label="Areas of interest"
    pivot-name="interest"
    pivot-error
    pivot-error-text="Please select at least one option"
    pivot-options='[
    { "label": "Design", "value": "design" },
    { "label": "Engineering", "value": "engineering" }
    ]'

    >
    </pivot-checkbox>

    <!-- Disabled group -->
    <pivot-checkbox
    pivot-fieldset-label="Areas of interest"
    pivot-name="interest"
    pivot-disabled
    pivot-options='[
    { "label": "Design", "value": "design" },
    { "label": "Engineering", "value": "engineering" }
    ]'

    >
    </pivot-checkbox>

    Implementation Notes

    • pivot-name is required for correct grouping behavior. All generated <input type="checkbox"> elements share this name. Without it, the browser cannot associate them as a group and form submissions will not key the values correctly.

    • pivot-options drives all rendered options. It can be set as a JSON string attribute (as shown above) or as a JavaScript property:

      const checkbox = document.querySelector("pivot-checkbox");
      checkbox.pivotOptions = [
      { label: "Design", value: "design" },
      { label: "Engineering", value: "engineering" },
      { label: "Research", value: "research" },
      ];
    • pivot-value pre-selects one or more options by matching each entry against option value fields. Pass a JSON array string to pre-check multiple items, or a plain string to pre-check a single item:

      <!-- Multiple pre-selected -->
      <pivot-checkbox pivot-value='["design", "research"]' ...></pivot-checkbox>

      <!-- Single pre-selected (plain string accepted for convenience) -->
      <pivot-checkbox pivot-value="design" ...></pivot-checkbox>

      As a JavaScript property, assign an array directly:

      checkbox.pivotValue = ["design", "research"];
    • 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.

    • In Angular, use dot-prefix property binding for pivot-options and pivot-value. Using [attr.pivot-options] or [attr.pivot-value] serializes the value to a string with mismatched quotes, JSON.parse fails silently, and the component receives []. Bind directly to the Lit property instead:

      checkboxOptions = [
      { label: 'Option A', value: 'a' },
      { label: 'Option B', value: 'b' },
      ];
      checkedValues: string[] = [];

      onCheckboxChange(event: CustomEvent<{ values: string[] }>) {
      this.checkedValues = event.detail.values;
      }
      <pivot-checkbox
      [attr.pivot-name]="name"
      .pivotOptions="checkboxOptions"
      .pivotValue="checkedValues"
      (pivot-checkbox-change)="onCheckboxChange($event)"
      >
      </pivot-checkbox>

      For options that are computed or loaded asynchronously, set the property directly on the element via @ViewChild:

      @ViewChild('checkboxRef') checkboxRef!: ElementRef<HTMLElement>;

      ngAfterViewInit() {
      (this.checkboxRef.nativeElement as any).pivotOptions = this.checkboxOptions;
      }

      Both approaches require CUSTOM_ELEMENTS_SCHEMA in the Angular component to suppress unknown-property errors.


    Companion form fields per option (CheckboxOption)

    Each entry in pivotOptions is a CheckboxOption:

    interface CheckboxOption {
    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 checked.

    When its option is checked, 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.


    Using the field-label-tooltip slot

    The field-label-tooltip slot accepts a single pivot-field-label-tooltip element rendered beside the fieldset legend. The fieldset legend itself is rendered by a shared renderFieldLabel helper directly into pivot-checkbox’s own shadow DOM. Before every render, pivot-checkbox checks its own light-DOM children for one with slot="field-label-tooltip", and sets its internal hasFieldLabelTooltip state accordingly — no event listener is involved. When hasFieldLabelTooltip is true, an info icon button is rendered inline with the group label; when no content is slotted, nothing extra is rendered. 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.

    <pivot-checkbox
    pivot-fieldset-label="Areas of interest"
    pivot-name="interest"
    pivot-options='[{ "label": "Design", "value": "design" }]'
    >

    <pivot-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-checkbox>

    See the pivot-field-label-tooltip documentation for full usage guidelines on the tooltip’s own content.


    Using the pivot-checkbox-change event

    pivot-checkbox fires pivot-checkbox-change once per individual checkbox toggle — not once per group render. Each time any single checkbox’s native change event fires, the component updates pivotValue and re-dispatches pivot-checkbox-change with the full, current set of checked values for the whole group (not just the value that was just toggled):

    document
    .querySelector("pivot-checkbox")
    .addEventListener("pivot-checkbox-change", (event) => {
    console.log(event.detail.values); // e.g. ["design", "research"]
    });

    The event bubbles and is composed, so it can also be caught by a listener attached higher up the DOM (e.g. on a parent pivot-form-container) without needing to bind to the checkbox element directly.


    Form Association

    pivot-checkbox sets static formAssociated = true, making it a form-associated custom element that integrates with ElementInternals internally. This means:

    • Its checked values are included in FormData when the parent form is submitted, using pivot-name as the key. Multiple checked values produce multiple entries under the same key (e.g. interest=design&interest=research).
    • 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.
    • pivot-checkbox 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 this component’s validity state is forwarded to ElementInternals via setValidity() after every update.

    Submission value

    setFormValue(FormData) is used internally so multiple checked values can be submitted under the same key. The submitted entries match whatever values are in pivotValue at submission time — the display labels are never submitted. When no options are checked, setFormValue(null) is called instead, so the field is treated as a non-successful control and omitted from FormData entirely rather than submitting an empty entry under pivot-name.

    Required validation

    When pivot-required is set and no options are checked, the component reports valueMissing: true via ElementInternals with the message “Please select at least one 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, so the group reports one message rather than one per checkbox.


    Validation and Error Display

    pivot-checkbox 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-checkbox
    pivot-fieldset-label="Areas of interest"
    pivot-name="interest"
    pivot-required
    pivot-options='[{ "label": "Design", "value": "design" }, { "label": "Research", "value": "research" }]'
    >
    </pivot-checkbox>
    <button type="submit">Submit</button>
    </form>
    <!-- Submitting with nothing checked renders "Please select at least one 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 checked) 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 current constraint-validation state (kept in sync with ElementInternals after every update) and returns whether the group 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 checkbox = document.querySelector(
    "pivot-checkbox[pivot-name='interest']",
    );
    checkbox.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 checkbox = document.querySelector(
    "pivot-checkbox[pivot-name='interest']",
    );
    checkbox.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 checkbox option row
    input <input type="checkbox"> Each checkbox input element
    label <label> Each option’s label element

    Accessibility

    pivot-checkbox is built entirely from native HTML form elements — <fieldset>, <legend>, <input type="checkbox">, and <label>. This means the browser and assistive technology handle the core accessible semantics with no additional ARIA required.

    • Always provide a meaningful pivot-fieldset-label. Screen readers announce the legend text as the group label when focus enters any checkbox in the group.
    • Do not leave pivot-fieldset-label empty. An unlabelled <fieldset> provides no context for screen reader users about what the group represents.
    • Use pivot-required when a selection is mandatory so the constraint is communicated to assistive technology via the validation message set on ElementInternals.
    • Keep pivot-error-text and pivot-helper-text concise and actionable. They are automatically associated with each checkbox input via aria-describedby — see Screen Reader Behavior below.
    • Each <label> is associated to its input via for / id, expanding the interactive hit target to include the label text. This benefits all users, especially on touch devices.

    ARIA Roles and Attributes

    The component relies on native HTML semantics and does not add custom ARIA roles.

    Element Implicit role Notes
    <fieldset> group Groups all checkboxes under a common label
    <legend> — Labels the <fieldset> group; announced when focus enters the group
    <input type="checkbox"> checkbox Carries aria-checked state managed by the browser
    <label> — Associated to each input via for / id; expands the clickable hit area
    • aria-invalid is set on each <input type="checkbox"> ("true"/"false"), reflecting the group’s error state — pivot-error, pivot-error-text, or a displayed native validation message (WCAG 4.1.2).
    • aria-describedby links each <input type="checkbox"> to pivot-field-helper-message whenever helper text, pivot-error-text, or a native validation message is present (WCAG 1.3.1, WCAG 4.1.3). The error text is additionally announced immediately via pivot-field-helper-message’s own role="alert", not only when a checkbox regains focus — see that component’s README.

    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 checkbox in the group.

    Screen Reader Behavior

    Expected behavior with the current implementation:

    • When focus enters a checkbox input, screen readers announce the input’s checked state, the associated label text, and the group name (from the <legend>).
    • Checking or unchecking a checkbox causes the new checked state to be announced immediately.
    • The helper or error message — including a native validation message rendered after a failed submit — is associated with each checkbox 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-checkbox inherits all standard keyboard behavior from native <input type="checkbox"> elements. Unlike radio inputs, each checkbox is independently focusable and togglable.

    Key Behavior
    Tab Moves focus to the next checkbox in the group (each is a tab stop).
    Shift + Tab Moves focus to the previous checkbox.
    Space Toggles the checked state of the focused checkbox.

    This matches the WAI-ARIA Authoring Practices Guide checkbox keyboard pattern.

    Checkbox vs. Radio keyboard behavior: Unlike radio groups — where arrow keys move focus and only one item can be selected — each checkbox in a group is an independent tab stop. Users Tab through each option and use Space to toggle individual items. Do not expect arrow key navigation between checkboxes.

    Focus Management

    • Focus is fully browser-managed through native checkbox inputs.
    • Each <input type="checkbox"> is an independent focusable element in the tab order, unlike radio inputs which share a single tab stop.
    • The component does not manually manage tabindex or override focus behavior.
    • The component relies on the browser’s native focus-visible rendering for checkbox inputs.
    • The component sets delegatesFocus: true via PivotBase, so focusing the host element will delegate focus to the first focusable internal element.
    • 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; delegatesFocus then moves focus to the first checkbox. The rendered error message is still announced via role="alert" (WCAG 3.3.1).

    Related Components


    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-checkbox pivot-optional>
    pivot-name string "" The `name` attribute shared by all checkbox inputs in the group. Required for correct grouping and form submission behaviour.
    pivot-value string[] [] Array of pre-selected option values. Can be set as a JSON array string attribute or as a JavaScript property. A plain string value is also accepted for single-selection convenience.
    pivot-error boolean false Presence of attribute means true: <pivot-checkbox pivot-error>
    pivot-required boolean false When true, at least one checkbox in the group must be checked for the group to be valid. Enforced via `ElementInternals`, not the native `required` attribute on individual inputs.
    pivot-disabled boolean false When true, all checkbox 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 CheckboxOption[] [] Array of checkbox 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-checkbox-change CustomEvent Fired when any checkbox in the group is toggled.

    CSS Custom Properties

    Name Description
    --component-field-control-general-gap Spacing used for the padding around each option row and between each checkbox input and its label.
    --component-field-label-gap Vertical spacing between an option's label row and its companion `pivot-input`/`pivot-text-area`/`pivot-date` field, if rendered. Also the horizontal gap between the fieldset legend's label text and its optional/required indicator or tooltip icon.
    --typography-body-md-size Font size for checkbox option labels, the fieldset legend label, and its "(optional)" indicator.
    --typography-body-md-height Line height for checkbox option labels, the fieldset legend label, and its "(optional)" indicator.
    --typography-constants-body-family Font family for the fieldset legend label and its "(optional)" indicator.
    --typography-icon-md-size Size of each checkbox input control.
    --global-color-icons-font-awesome-primary-color Accent color for checkbox 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 checkbox inputs.
    --global-color-text-on-light-error-color Option label color used in the error state, and the color of the required "*" indicator beside the fieldset legend label. Helper and error message text colors are handled by `pivot-field-helper-message`.
    --global-color-text-on-light-light-color Text color of the "(optional)" indicator beside the fieldset legend label.
    --component-field-label-color Text color of the fieldset legend label.
    --component-input-field-input-disabled Label color used when the component is disabled.