Pivot Docs

    Field Label Tooltip

    pivot-field-label-tooltip is an info-icon button that, when activated, opens a popover with a header and descriptive content. It is designed to surface supplemental, non-essential context alongside a form field label. The click-activated disclosure remains open until explicitly dismissed.

    This component must only be used inside a supported form component slot. It is not a standalone component. Never place it outside of a form component (such as pivot-input, pivot-checkbox, pivot-date, pivot-radio, pivot-selector, or pivot-text-area). See Supported Form Components.


    Quick Start

    <pivot-input pivot-name="routing-number" pivot-label="Routing number">
    <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-input>

    Overview

    The component renders an info icon (ⓘ) button inline with the field label. Activating the button opens a popover anchored to the button, positioned above by default and falling back to below when space is limited. The popover includes:

    • A header driven by the pivot-tooltip-popover-header attribute.
    • A description area populated by the component’s child content (its default slot).
    • A close button (×) that dismisses the popover.

    The popover uses the browser-native Popover API (popover="auto"), which means it also dismisses automatically when the user clicks outside of it or presses Escape.


    Supported Form Components

    pivot-field-label-tooltip is only supported in the following slot contexts. Place it as a direct child of the form component with slot="field-label-tooltip". The attribute is required — a tooltip without it is not rendered, and the host component logs a console warning naming the element. Each component renders the field-label-tooltip slot beside its field label using the shared renderFieldLabel() helper:

    Component Slot name
    pivot-input field-label-tooltip
    pivot-checkbox field-label-tooltip
    pivot-date field-label-tooltip
    pivot-radio field-label-tooltip
    pivot-selector field-label-tooltip
    pivot-text-area field-label-tooltip

    pivot-search-hero does not support this slot.

    Additional form components may add support for this slot in the future.


    When to Use

    Use this component when a form field requires additional context that some — but not all — users will need, and where that context is not essential for task completion.

    Good candidates:

    • Clarifying why a specific piece of information is being collected (e.g., “Why do we ask for your SSN?”).
    • Providing an example value or format that supplements — but doesn’t replace — a label or placeholder.
    • Explaining an unfamiliar term used in the label.

    When Not to Use

    • Do not use for information that is required to complete the task. If a user must see the content to fill in the field correctly (for example, password requirements or field format rules), it belongs in pivot-helper-text instead, which is always visible.
    • Do not use for redundant information. If the tooltip content just repeats the label, it adds noise without value.
    • Do not replace a label. The field label must always be present and meaningful on its own.
    • Do not add interactive elements to the description content beyond what the component provides. Users who rely on keyboard navigation or assistive technology expect the popover content to be informational, not a sub-form.
    • Do not use this component independently. It must always be slotted inside a supported form component.

    Using the default slot

    The popover body is the component’s default slot — place the description content directly inside pivot-field-label-tooltip, with no slot attribute. Multiple children are rendered in order:

    <pivot-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-text>
    You can also find it on your bank's mobile app under account details.
    </pivot-text>
    </pivot-field-label-tooltip>

    Accepts pivot-text and <p> elements. Margin and padding are reset for slotted <p> elements by the component’s styles. Do not slot forms, inputs, or buttons — see When Not to Use.


    Implementation Notes

    • The popover is opened and closed using the browser-native Popover API. No JavaScript event handling beyond what the browser provides is required to open, close, or dismiss it.
    • The popover uses popover="auto", which means:
      • Clicking outside the popover or pressing Escape will close it automatically.
      • Only one auto popover can be open at a time per top layer — opening a second tooltip closes any other open auto popover on the page.
    • The trigger button’s accessible label defaults to "Additional information" and can be overridden with pivot-tooltip-aria-label. Always ensure the label is meaningful for the specific field context.
    • The popover is positioned using CSS anchor positioning (position-anchor) with a fallback to clip-path shape for browsers without border-shape support. The caret visually connects the popover to its trigger.
    • The component renders inline — it participates in the flex layout of the input-label-container rendered by the host form component’s field label.
    • pivot-field-label-tooltip does not dispatch any custom events. Its job is purely to render the icon and popover.

    Accessibility

    This component follows an interactive disclosure (“toggletip”) pattern rather than the WAI-ARIA tooltip role pattern. That distinction is deliberate: the ARIA tooltip role is defined for non-interactive, hover/focus-triggered content only, and this popover contains an interactive close button and is triggered by a click — using role="tooltip" here would be a misuse of that role. Instead, the component relies on plain, well-supported semantics: a native <button> and the browser-native Popover API.

    Screen Reader Behavior

    • The trigger renders as a native <button> with an aria-label (defaulting to "Additional information", overridable via pivot-tooltip-aria-label). Screen readers announce it as a button with that accessible name — there is no visible text label, so a generic default like "Additional information" should be overridden with field-specific text (e.g., "Additional information about routing number") whenever the default would be ambiguous in context.
    • aria-expanded on the trigger button is kept in sync with the popover’s open state via the native toggle event, so assistive technology can announce whether the popover is currently expanded or collapsed.
    • The popover header and description are rendered as plain visible text (no role="dialog" or similar landmark role is applied), so screen readers announce them as ordinary content once focus or reading order reaches them.
    • The component does not set aria-describedby from the trigger button to the popover content, and does not set aria-haspopup. Consumers should not assume the relationship between the trigger and the popover content is announced beyond the aria-expanded state change — verify behavior with real screen reader and browser combinations before relying on it for anything critical.

    Keyboard Navigation

    Key Behavior
    Tab Moves focus to the info icon trigger button.
    Space / Enter Opens the popover when the trigger button is focused.
    Tab When the popover is open, moves focus to the close (×) button inside (the next focusable element in document order).
    Space / Enter Activates the close button to dismiss the popover.
    Escape Dismisses the popover at any time while it is open (native Popover API).

    Focus Management

    • Opening the popover does not programmatically move focus into it — the component sets no autofocus element and calls no .focus(). Focus remains on the trigger button until the user tabs forward.
    • Closing the popover while focus is inside it (for example, after activating the close button, or pressing Escape while the close button is focused) returns focus to the trigger button. This is native Popover API behavior, not custom logic in this component.
    • Dismissing the popover by clicking outside of it does not move focus, since focus was already outside the popover at the time of dismissal.
    • The component does not trap focus inside the popover. Tabbing past the close button moves focus to whatever follows the tooltip in the surrounding form component’s document order.

    WCAG 2.2 AA Considerations

    • 1.4.13 Content on Hover or Focus — this component sidesteps the most common tooltip failure mode here: because the popover is opened only by an explicit click (not by hover or focus), 1.4.13’s hover/focus-triggered-content requirements (dismissible, hoverable, persistent) do not strictly apply. The popover is dismissible (Escape, close button, or outside click) and persistent (it does not disappear on mouse movement), so it comfortably meets the spirit of this criterion regardless.
    • 2.1.1 Keyboard — the trigger, popover close button, and dismissal are all operable from the keyboard as documented above.
    • 2.4.7 Focus Visible — the trigger and close button are native, unstyled-for-focus <button> elements; verify that the design system’s global focus-visible styles are not being suppressed by this component’s CSS (they are not, as of this writing — no outline or :focus overrides appear in field-label-tooltip.css).
    • Real gap: as noted above, there is no aria-describedby (or equivalent) association exposed between the trigger and the popover content, and no aria-haspopup. This is a legitimate accessibility gap worth tracking if stricter AT support is required.

    Related standards:


    Content Guidelines

    • Keep header text brief. A short phrase or question works best (e.g., "What is a routing number?"). Avoid long sentences.
    • Keep description text focused. One to three sentences is usually sufficient. The description should add real value — if you can’t explain why the user needs this information, leave the tooltip out.
    • Write for the user who is confused, not the expert. The tooltip exists to help users who need more context, not to restate what is already clear from the label.
    • Do not include critical task requirements here. Content that a user must act on to successfully complete the field belongs in pivot-helper-text.
    • Use pivot-text or <p> for description content. Margin and padding are reset for slotted <p> elements by the component’s styles.

    Browser Support

    Feature Notes
    Popover API (popover="auto") Supported in modern browsers. Graceful degradation may occur in unsupported environments.
    CSS Anchor Positioning Used for popover placement. Fallbacks are in place for browsers without support.
    border-shape Used for the caret shape. Falls back to clip-path for unsupported browsers.
    @container anchored(fallback:) Used for position-sensitive padding. Treated as unknown at-rule in older browsers.

    Related Components


    References


    API Reference

    Props

    Name Type Default Description
    pivot-tooltip-aria-label string "Additional information" This will create an attribute: aria-label="value" on the info icon button.
    pivot-tooltip-popover-header string "" This adds a header to the tooltip popover.

    Slots

    Name Description
    default Description content shown in the tooltip popover.

    CSS Custom Properties

    Name Description
    --typography-icon-md-size Size of the info icon trigger.
    --global-color-icons-font-awesome-info-color Color of the info icon trigger.
    --component-card-radius Corner radius of the popover and its caret.
    --global-space-primitives-4 Gap between the popover header and description.
    --global-space-semantic-space-gutter Internal padding of the popover.
    --global-color-text-on-light-light-color Text color of the popover description.
    --global-color-surface-1-color Background color of the popover.
    --component-divider-default Border color of the popover.
    --global-elevation-shadow1-x Horizontal offset of the popover drop shadow.
    --global-elevation-shadow1-y Vertical offset of the popover drop shadow.
    --global-elevation-shadow1-blur Blur radius of the popover drop shadow.
    --global-elevation-shadow1-spread Spread radius of the popover drop shadow.
    --global-elevation-shadow1-fill Color of the popover drop shadow.
    --typography-constants-body-family Font family of the popover header and description.
    --typography-body-md-size Font size of the popover header and description.
    --typography-body-md-height Line height of the popover header and description.
    --global-color-text-on-light-header-color Text color of the popover header.
    --typography-icon-lg-height Size of the close button's hit target.
    --typography-icon-lg-size Size of the close button icon.
    --global-color-icons-font-awesome-default-color Color of the close button icon.