feat(tooltip): add pf-v6-tooltip element by bennypowers · Pull Request #3141 · patternfly/patternfly-elements

bennypowers · 2026-05-11T17:29:16Z

Summary

New pf-v6-tooltip element ported from v5 with v6 design tokens
FloatingDOMController with arrow element positioning
Cancellable TooltipShowEvent/TooltipHideEvent with reason enum for selective trigger prevention
trigger attribute (IDREF) and property (Element ref) for external trigger elements
entry-delay/exit-delay (default 300ms), alignment (start/end/left/right), position, no-flip, flip-behavior
light-dark() CSS fallbacks for correct inverse color scheme
ariaDescribedByElements wiring between trigger and tooltip content
9 demos: basic, placement, trigger-ref, trigger-element, slotted-content, dynamic-content, left-aligned, color-scheme, options playground
17 unit tests

Test plan

Verify tooltip shows on hover and focus in all demos
Verify tooltip hides on mouseleave, focusout, and Escape
Verify light-dark color scheme inversion in color-scheme demo
Verify external trigger via IDREF (trigger-ref) and Element ref (trigger-element)
Verify alignment attribute changes text-align
Verify entry-delay/exit-delay in options playground
Verify no-flip disables repositioning
Run /review-a11y, /review-api, /review-demos
Visual parity with patternfly.org tooltip

Closes #3048

changeset-bot · 2026-05-11T17:29:23Z

🦋 Changeset detected

Latest commit: b52089b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@patternfly/elements	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-05-11T17:30:19Z

✅ Commitlint tests passed!

More Info

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "input": "feat(tooltip): add pf-v6-tooltip element"
}

github-actions · 2026-05-11T17:31:24Z

✅ Deploy Preview for patternfly-elements ready!

Name	Link
🔨 Latest commit	`d88bd77`
😎 Deploy Preview	https://deploy-preview-3141--patternfly-elements.netlify.app/

To edit notification comments on pull requests, go to your Netlify site settings.

github-actions · 2026-05-11T17:32:36Z

SSR Test Run for 4e4a328: Report

Port tooltip to v6 design tokens and patterns. - FloatingDOMController with arrow element positioning - Cancellable TooltipShowEvent/TooltipHideEvent with reason enum - `trigger` attribute (IDREF) and property (Element ref) - `entry-delay`/`exit-delay` attributes (default 300ms) - `alignment` attribute (start/end/left/right) - `position`, `no-flip`, `flip-behavior` carried from v5 - `light-dark()` CSS fallbacks for inverse color scheme - `ariaDescribedByElements` wiring on show/hide - Escape key dismissal - 9 demos including playground, color-scheme, and element-ref trigger - 17 unit tests covering API, a11y, events, and cancellation Closes #3048 Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replaced by pf-v6-tooltip. Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-05-14T10:07:34Z

SSR Test Run for 6b79b33: Report

github-actions · 2026-05-25T12:20:39Z

SSR Test Run for d88bd77: Report

bennypowers · 2026-05-25T21:14:39Z

Cross-root `aria-describedby` limitation

The tooltip sets ariaDescribedByElements on the trigger to reference the shadow-internal #content div. This is the correct API for cross-root ARIA relationships, but it silently fails in all browsers today: the accessibility tree shows no describedby relationship.

Per the current spec, ARIA element reflection only works when shadow roots are in an ancestor/descendant relationship, and even then only in the shadow-to-light direction. Our use case (light DOM trigger referencing shadow DOM content) goes the wrong way. The WPT test explicitly asserts that cross-root refs produce an empty computed label.

This means tooltip triggers currently have no programmatic describedby relationship in any browser. The tooltip content is still announced when visible (via role="tooltip" and proximity in the accessibility tree), but there is no formal ARIA association.

The Reference Target proposal (Chrome origin trial) would solve the slotted trigger case. The external trigger case (sibling elements) would need the relaxation discussed in WICG/aom#192. Both whatwg/html#5401 and whatwg/html#10707 track the broader spec work.

Keeping the ariaDescribedByElements call as progressive enhancement -- it will start working once browsers ship a solution. No workaround attempted; the alternatives (hidden light DOM spans, aria-label mirroring) add complexity for a temporary gap.

@adamjohnson and @hellogreg -- could you verify the actual screen reader experience here? Want to confirm the tooltip content is still announced via proximity/role="tooltip" even without the formal describedby association.

- Static document keydown listener for Escape (works with external triggers) - Screen reader announcer via static `role="status"` live region - `silent` attribute to opt out of announcements - Remove physical `'left'`/`'right'` from `TooltipAlignment`, keep logical `'start'`/`'end'` only - Remove `color-scheme: light dark` from `:host` so tooltip inherits container scheme and inverts correctly via `light-dark()` - Fix `user-select: initial` to `auto` - Why-comments on `ariaDescribedByElements` cross-root limitation and intentional bidirectional `visible` state - Improved JSDoc for cem health (66 -> 85): element description, slot a11y notes, CSS token refs, event detail shapes, added missing `--pf-v6-c-tooltip__arrow--BoxShadow` `@cssprop` Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- hide event firing and reason - focusin/focusout triggers - Element reference trigger property - flip-behavior attribute parsing - visible attribute (declarative) - slot overrides content attribute - cancel hide event - Escape key with external trigger (document listener) - silent attribute Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrate feature parity with React trigger modes using cancelable show/hide events: - click-trigger: click-to-toggle tooltip via preventDefault on hover - manual-trigger: checkbox-controlled tooltip via preventDefault on both hover and focus triggers Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Not a standalone demo on patternfly.org; alignment is covered by the options playground demo. Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add static live-region announcer pattern for tooltip/popover content (from rh-tooltip) - Update cross-root ARIA section with WPT test link and spec references (WICG/aom#192, whatwg/html#5401, WICG/webcomponents#1086) Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zeroedin

Rename PR feat(tooltip)!: port to pf-v6-tooltip

zeroedin · 2026-06-12T14:53:21Z

+"@patternfly/elements": minor
+---
+
+`pf-v6-tooltip`: New tooltip element with hover/focus activation, configurable placement, entry/exit delays, flip behavior, external trigger support, rich content via slot, and cancelable show/hide events.


This should be a major and follow the major changeset format

--- "@patternfly/elements": major --- ✨ Added `<pf-v6-tooltip>` replacing `<pf-v5-tooltip>`. Tooltip now follows PatternFly v6 design specs. {{ example usage here }} ** Breaking Changes from v5 ** - {{Breaking changes here}}

zeroedin · 2026-06-12T14:57:50Z

+| `animationDuration`        | CSS transitions                       | Override via stylesheet instead of prop                                                 |
+| `distance`                 | Hardcoded 15px                        | Not configurable; React default also 15                                                 |
+| `isVisible`                | `visible`                             | Boolean attribute; also controllable via `.show()` / `.hide()` methods                  |
+| `minWidth`                 | Not supported                         | No CSS custom property exposed                                                          |


minWidth should be moved to Not Implemented.

zeroedin · 2026-06-12T15:10:15Z

+| `distance`                 | Hardcoded 15px                        | Not configurable; React default also 15                                                 |
+| `isVisible`                | `visible`                             | Boolean attribute; also controllable via `.show()` / `.hide()` methods                  |
+| `minWidth`                 | Not supported                         | No CSS custom property exposed                                                          |
+| `zIndex`                   | Not supported                         | Hardcoded to 10000 in shadow DOM                                                        |


I'm hesitant about the hardcoded value here. I feel like we should offer a way to change it. I understand that there is no current CSS var, react is using an inline style prop drill. I can see this as an issue in some implementations if it cannot be fixed. Edge cases, sure, but hard-coding a high z-index is a bad practice.

would it be better to offer a net new css var here to allow an escape hatch and document it under "Added"?

zeroedin · 2026-06-12T15:12:07Z

+| `hide` event                  | Cancelable event before tooltip hides, with trigger `reason`        |
+| `.show()` / `.hide()` methods | Programmatic visibility control                                     |
+| `content` slot                | Rich HTML content, not available in React (which takes `ReactNode`) |
+| CSS custom properties         | 13 custom properties for fine-grained style control without JS      |


The CSS properties not not "Added" this line should be removed

github-actions Bot added the AT passed Automated testing has passed label May 11, 2026

bennypowers added 3 commits May 12, 2026 10:08

feat(tooltip): delete pf-v5-tooltip

2bd0449

Replaced by pf-v6-tooltip. Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: update v5 tooltip importers to use pf-v6-tooltip

683110f

Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

bennypowers force-pushed the feat/tooltip/v6 branch from 0b0a955 to 683110f Compare May 12, 2026 08:00

This comment has been minimized.

Sign in to view

fix: update remaining pf-v5-tooltip references in docs and CSS

a605582

Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

bennypowers marked this pull request as ready for review May 12, 2026 11:19

bennypowers added 2 commits May 14, 2026 13:04

feat(tooltip): add visible boolean

e45abd5

docs(tooltip): add README.md

75be1fb

Merge remote-tracking branch 'origin/staging/pfv6' into feat/tooltip/v6

6872409

bennypowers added 6 commits May 26, 2026 11:17

chore(tooltip): remove redundant left-aligned demo

ac2b177

Not a standalone demo on patternfly.org; alignment is covered by the options playground demo. Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore(tooltip): add changeset

b52089b

Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zeroedin self-requested a review June 11, 2026 14:33

zeroedin reviewed Jun 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(tooltip): add pf-v6-tooltip element#3141

feat(tooltip): add pf-v6-tooltip element#3141
bennypowers wants to merge 13 commits into
staging/pfv6from
feat/tooltip/v6

bennypowers commented May 11, 2026

Uh oh!

changeset-bot Bot commented May 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 11, 2026

Uh oh!

This comment has been minimized.

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 25, 2026

Uh oh!

bennypowers commented May 25, 2026 •

edited

Loading

Uh oh!

zeroedin left a comment

Uh oh!

zeroedin Jun 12, 2026

Uh oh!

zeroedin Jun 12, 2026

Uh oh!

zeroedin Jun 12, 2026

Uh oh!

zeroedin Jun 12, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

bennypowers commented May 11, 2026

Summary

Test plan

Uh oh!

changeset-bot Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Commitlint tests passed!

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for patternfly-elements ready!

Uh oh!

github-actions Bot commented May 11, 2026

Uh oh!

This comment has been minimized.

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 25, 2026

Uh oh!

bennypowers commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Cross-root aria-describedby limitation

Uh oh!

zeroedin left a comment

Choose a reason for hiding this comment

Uh oh!

zeroedin Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

zeroedin Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

zeroedin Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

zeroedin Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading

bennypowers commented May 25, 2026 •

edited

Loading

Cross-root `aria-describedby` limitation

zeroedin Jun 12, 2026 •

edited

Loading