Tooltip: Expose controlled props (open, defaultOpen, onOpenChange) on Root

[haqadn]

What?

Expose open, defaultOpen, and onOpenChange props on Tooltip.Root in @wordpress/ui.

Why?

Tooltip.Root currently only exposes disabled and children from Base UI's Tooltip.Root.Props, which blocks consumers from building controlled or click-triggered tooltips. Base UI already supports these props and the Root component already spreads all props through, so this is purely a type widening. This follows the same pattern used by AlertDialog.Root and Dialog.Root in this codebase.

How?

• Widened RootProps in packages/ui/src/tooltip/types.ts to pick open, defaultOpen, and onOpenChange in addition to the existing disabled and children.
• No runtime changes needed — root.tsx already spreads all props to the Base UI component.
• Added a unit test verifying the controlled open prop renders the tooltip without hover.
• Added a Controlled Storybook story demonstrating click-to-toggle usage.

Testing Instructions

1. Run npm run test:unit packages/ui/src/tooltip — all tests pass, including the new controlled-open test.
2. Run npx storybook dev and navigate to Tooltip > Controlled — clicking the "Toggle tooltip" button should show/hide the tooltip.
3. Verify TypeScript compiles: npx tsc -p packages/ui/tsconfig.json --noEmit.

Testing Instructions for Keyboard

1. Tab to the "Toggle tooltip" button in the Controlled story.
2. Press Enter/Space to toggle the tooltip visibility.

Use of AI Tools

This PR was authored with the assistance of Claude Code (Claude Opus 4.6).

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: haqadn <adnan007@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @haqadn! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[mirka]

Tooltip.Root currently only exposes disabled and children from Base UI's Tooltip.Root.Props, which blocks consumers from building controlled or click-triggered tooltips.

Can you elaborate on this? What is your specific use case that requires these props to be exposed?

I'm not necessarily opposed to exposing those Root props, but I'm also concerned about misuse of the component and want to make sure we're not broadening the API surface for use cases that we're explicitly discouraging in the design system.

[haqadn]

Can you elaborate on this? What is your specific use case that requires these props to be exposed?

I am trying to workaround a UX issue where clicking the tooltips keeps them closed. A user can think the information icon is supposed to be clicked, and when they do click it, it ends up keeping it closed. Having the API exposed would allow working around this by controlling the behavior without changing the base component. @mirka

[ciampo]

@haqadn Tooltips are meant to provide brief, non-interactive hints on hover or focus, and per the WAI-ARIA Authoring Practices, they should dismiss when that state changes. Clicking a button changes the interaction context (often triggering an action or opening another UI), so the tooltip is normally expected to close to avoid stale or conflicting UI.

Looking at that example, I'm confused to why we'd expect end users to click on that info icon - isn't hovering enough?
If the content is important, lengthy, needs to remain visible, or to be interactive after click, it’s usually a sign that a tooltip isn’t the right pattern and a popover or dialog should be used instead.

[haqadn]

Looking at that example, I'm confused to why we'd expect end users to click on that info icon - isn't hovering enough?
If the content is important, lengthy, needs to remain visible, or to be interactive after click, it’s usually a sign that a tooltip isn’t the right pattern and a popover or dialog should be used instead.

I think tooltip is right here given the intention. My concern is more about the UX. In the example, the reporter thought the tooltips are broken. Because, they assumed it was supposed to open on click rather than hover. With the APIs open, it would have been possible to tweak the interaction slightly.

Clicking a button changes the interaction context (often triggering an action or opening another UI), so the tooltip is normally expected to close to avoid stale or conflicting UI.

That is not the case for the example, so it would have been fine to tweak the behavior a little bit so the tooltip doesn't reset on click. This is what I am trying to do with the exposed API.

[mirka]

Thanks for elaborating @haqadn, it helps for us to understand what developers need from our component set.

That is an "infotip" pattern, and Tooltip is not intended for this use case as currently stated in our documentation, as well as in the upstream docs in Base UI.

I'm hoping to add an official Infotip component to @wordpress/ui, but for the time being, I recommend building your own using a plain Popover.

[ciampo]

I'm hoping to add an official Infotip component to @wordpress/ui, but for the time being, I recommend building your own using a plain Popover.

The @wordpress/ui Popover , which should provide 99% of the necessary functionality for the infotip, should be available very soon (currently in progress in #76438)

[ciampo]

@haqadn to close the loop:

• new Tooltip documentation clarifying usage guidelines
• Popover component was merged, including an Infotip example (which may soon even become a dedicated component)

Hope this can help!