facebook / facebook/docusaurus
Proposal: Global CSS Anchor Positioning Tooltip System
- 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
Assessment
This issue has not been assessed yet.