facebook / facebook/docusaurus

Proposal: Global CSS Anchor Positioning Tooltip System

Open
#11,894 1 comment 0 reactions 0 assignees View on GitHub
proposal status: needs triage
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

### Have you read the Contributing Guidelines on issues?

- [x] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).

### Motivation

Currently, the Docusaurus classic theme relies on native browser tooltips (via the `title` attribute) for elements like the `ColorModeToggle`, navbar items, and action buttons. These native tooltips have a built-in OS delay, cannot be styled to fit the Infima theme, and disrupt the premium interactive feel of modern documentation sites.

Following feedback from @slorber on PR #11891, I am proposing the introduction of a comprehensive, global Tooltip system to Docusaurus using modern CSS—specifically the CSS Anchor Positioning API—to replace native tooltips across the whole theme.

### Proposed Architecture

**1. CSS Anchor Positioning API**
To avoid expanding the JavaScript bundle with heavy positioning libraries like Floating UI or Popper.js, we can tether the tooltip to its trigger element using the [CSS Anchor Positioning API](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning). This keeps the framework lean while delivering robust, responsive positioning.
*(Note: As Anchor Positioning is still gaining baseline support, a gracefully degraded CSS fallback would be included for unsupported browsers).*

**2. Component API**
Introduce a headless, reusable `` component in `docusaurus-theme-common` and a beautifully styled implementation in `docusaurus-theme-classic`.

Example concept:
```tsx
import Tooltip from '@theme/Tooltip';

### Self-service

- [x] I'd be willing to do some initial work on this proposal myself.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.