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, orpivot-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-headerattribute. - 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-textinstead, 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
Escapewill close it automatically. - Only one
autopopover can be open at a time per top layer — opening a second tooltip closes any other open auto popover on the page.
- Clicking outside the popover or pressing
- The trigger button’s accessible label defaults to
"Additional information"and can be overridden withpivot-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 toclip-pathshape for browsers withoutborder-shapesupport. The caret visually connects the popover to its trigger. - The component renders inline — it participates in the flex layout of the
input-label-containerrendered by the host form component’s field label. pivot-field-label-tooltipdoes 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 anaria-label(defaulting to"Additional information", overridable viapivot-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-expandedon the trigger button is kept in sync with the popover’s open state via the nativetoggleevent, 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-describedbyfrom the trigger button to the popover content, and does not setaria-haspopup. Consumers should not assume the relationship between the trigger and the popover content is announced beyond thearia-expandedstate 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
autofocuselement 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
Escapewhile 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 — nooutlineor:focusoverrides appear infield-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 noaria-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-textor<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
- Input, Checkbox, Date, Radio, Selector, Text Area — the supported host components; see Supported Form Components above.
References
- W3C WAI-ARIA APG: Tooltip Pattern
- Carbon Design System: Tooltip Usage
- Carbon Design System: Toggletip
- MDN: Popover API
- Nielsen Norman Group: Tooltip Guidelines
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. |
pivot-field-label-tooltip is not a standalone component — in real usage it must always be slotted into a supported form component’s field-label-tooltip slot (pivot-input, pivot-checkbox, pivot-date, pivot-radio, or pivot-text-area; see Supported Form Components). The demos below render it in isolation, without a host component or a slot="field-label-tooltip" attribute, to focus on its own props and popover behavior — neither affects how this component itself renders or behaves.
Basic tooltip (header and description)
Use a tooltip to explain what a field is or where to find the value — context that helps some users but isn't required to complete the field.
<pivot-field-label-tooltip
pivot-tooltip-popover-header="Where to find your routing number"
>
<pivot-text>
Your 9-digit routing number is printed at the bottom-left of a personal
check, before your account number.
</pivot-text>
</pivot-field-label-tooltip>Custom trigger label for a sensitive field (pivot-tooltip-aria-label)
The trigger button's accessible name defaults to "Additional information". Override it with pivot-tooltip-aria-label so screen reader users hear field-specific context instead of a generic label — especially important for sensitive-data fields.
<pivot-field-label-tooltip
pivot-tooltip-aria-label="Why we ask for your Social Security Number"
pivot-tooltip-popover-header="Why we ask for this"
>
<pivot-text>
Federal law requires us to verify your identity. Your SSN is encrypted and
never shared with third parties.
</pivot-text>
</pivot-field-label-tooltip>Multiple description paragraphs
The label-tooltip-description slot accepts more than one child. Each is rendered in order inside the popover body.
<pivot-field-label-tooltip
pivot-tooltip-popover-header="Where to find your routing number"
>
<pivot-text>
Your 9-digit routing number is printed at the bottom-left of a personal
check, before your account number.
</pivot-text>
<pivot-text>
You can also find it on your bank's mobile app under account details.
</pivot-text>
</pivot-field-label-tooltip>Auto-assigned description content (no explicit slot attribute)
A child with no slot attribute is automatically re-homed to label-tooltip-description on connect. Being explicit is still recommended (see the examples above), but this works for the common single-child case.
<pivot-field-label-tooltip
pivot-tooltip-popover-header="What is a routing number?"
>
<!-- No slot attribute needed — auto-assigned to label-tooltip-description -->
<pivot-text>
Your 9-digit routing number is printed at the bottom-left of your personal
check.
</pivot-text>
</pivot-field-label-tooltip>