Skip to content

Commit 7d3bed0

Browse files
danielbariondanielbarion
committed
docs: update changelog and add portal root doc
1 parent 9b8f086 commit 7d3bed0

9 files changed

Lines changed: 311 additions & 56 deletions

File tree

‎docs/docs/examples/portal-root.mdx‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Portal Root
6+
7+
Render the tooltip into a custom DOM container with `portalRoot`.
8+
9+
This is useful when the tooltip needs to escape local clipping, stacking, or layout constraints.
10+
11+
import React, { useEffect, useRef, useState } from 'react'
12+
import { Tooltip } from 'react-tooltip'
13+
14+
export const TooltipAnchor = ({ children, id, ...rest }) => {
15+
return (
16+
<span
17+
id={id}
18+
style={{
19+
display: 'flex',
20+
justifyContent: 'center',
21+
alignItems: 'center',
22+
width: '60px',
23+
height: '60px',
24+
borderRadius: '60px',
25+
color: '#222',
26+
background: 'rgba(255, 255, 255, 1)',
27+
cursor: 'pointer',
28+
boxShadow: '3px 4px 3px rgba(0, 0, 0, 0.5)',
29+
border: '1px solid #333',
30+
}}
31+
{...rest}
32+
>
33+
{children}
34+
</span>
35+
)
36+
}
37+
38+
export const PortalRootExample = () => {
39+
const portalContainerRef = useRef(null)
40+
const [portalRoot, setPortalRoot] = useState(null)
41+
42+
useEffect(() => {
43+
setPortalRoot(portalContainerRef.current)
44+
}, [])
45+
46+
return (
47+
<div
48+
style={{
49+
display: 'grid',
50+
gap: '1rem',
51+
justifyItems: 'center',
52+
}}
53+
>
54+
<div
55+
style={{
56+
width: '100%',
57+
maxWidth: '580px',
58+
overflow: 'hidden',
59+
border: '1px solid #cbd5e1',
60+
borderRadius: '16px',
61+
padding: '1.25rem',
62+
background:
63+
'linear-gradient(180deg, rgba(248,250,252,1) 0%, rgba(241,245,249,1) 100%)',
64+
}}
65+
>
66+
<p style={{ margin: 0, textAlign: 'center', color: '#475569' }}>
67+
This panel clips its content. The tooltip is rendered into the container below instead of
68+
staying inside this box.
69+
</p>
70+
<div
71+
style={{
72+
display: 'flex',
73+
justifyContent: 'center',
74+
paddingTop: '1rem',
75+
}}
76+
>
77+
<TooltipAnchor data-tooltip-id="my-tooltip-portal-root">◕‿‿◕</TooltipAnchor>
78+
</div>
79+
</div>
80+
81+
<div
82+
ref={portalContainerRef}
83+
style={{
84+
width: '100%',
85+
maxWidth: '580px',
86+
minHeight: '96px',
87+
border: '1px dashed #0f766e',
88+
borderRadius: '16px',
89+
padding: '1rem',
90+
background: 'rgba(240, 253, 250, 1)',
91+
position: 'relative',
92+
}}
93+
>
94+
<p style={{ margin: 0, textAlign: 'center', color: '#115e59' }}>
95+
Tooltip portal container
96+
</p>
97+
</div>
98+
99+
<Tooltip
100+
id="my-tooltip-portal-root"
101+
content="Rendered through portalRoot"
102+
portalRoot={portalRoot}
103+
positionStrategy="fixed"
104+
/>
105+
</div>
106+
)
107+
}
108+
109+
### Basic usage
110+
111+
```jsx
112+
import React, { useEffect, useRef, useState } from 'react'
113+
import { Tooltip } from 'react-tooltip'
114+
115+
function Example() {
116+
const portalContainerRef = useRef(null)
117+
const [portalRoot, setPortalRoot] = useState(null)
118+
119+
useEffect(() => {
120+
setPortalRoot(portalContainerRef.current)
121+
}, [])
122+
123+
return (
124+
<>
125+
<button data-tooltip-id="my-tooltip">Hover me</button>
126+
<div ref={portalContainerRef} />
127+
<Tooltip
128+
id="my-tooltip"
129+
content="Rendered through portalRoot"
130+
portalRoot={portalRoot}
131+
positionStrategy="fixed"
132+
/>
133+
</>
134+
)
135+
}
136+
```
137+
138+
<PortalRootExample />
139+
140+
### Notes
141+
142+
- `portalRoot` is optional. Without it, the tooltip renders inline as usual.
143+
- `positionStrategy="fixed"` is the safest default when rendering into `document.body` or another external container.
144+
- The anchor element stays in place. Only the tooltip node is moved.

‎docs/docs/upgrade-guide/changelog-v5-v6.md‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,46 @@ sidebar_position: 2
44

55
# Changelog V5 -> V6
66

7-
If you are using V5 and want to upgrade to V6, the main change is the removal of the raw HTML string API.
7+
If you are using V5 and want to upgrade to V6, the biggest breaking change is the removal of the raw HTML string API, but it is not the only difference worth checking before migrating.
88

99
## From V5 to V6
1010

11-
V6 keeps the core tooltip behavior from V5, but removes legacy HTML-string entry points so tooltip content stays in React nodes instead of injected markup strings.
11+
V6 keeps the core tooltip behavior from V5, but updates the implementation and API around a few key areas:
12+
13+
- rich tooltip content is rendered through React nodes instead of injected HTML strings
14+
- runtime behavior is lighter and more scalable in larger interfaces
15+
- React 19 is supported while React 16.14+ remains compatible
16+
- optional `portalRoot` support lets you render the tooltip into a custom DOM container when you need tighter control over clipping and overlay layout
1217

1318
## Breaking Changes
1419

1520
- `data-tooltip-html` was removed
1621
- `html` prop was removed
1722
- Raw HTML string examples should now be implemented with `children` or `render`
1823

24+
## New And Updated Capabilities
25+
26+
- `children` and `render` are the preferred way to render rich tooltip content in v6
27+
- `portalRoot` is available when the tooltip should render into a specific DOM node, such as `document.body`
28+
- v6 includes internal runtime improvements that reduce mount cost, memory retention, and shipped bundle size relative to v5
29+
30+
## `portalRoot`
31+
32+
When a layout clips overlays or makes stacking difficult, you can render the tooltip into a separate container:
33+
34+
```jsx
35+
<Tooltip
36+
id="my-tooltip"
37+
content="Hello"
38+
portalRoot={document.body}
39+
positionStrategy="fixed"
40+
/>
41+
```
42+
43+
`portalRoot` is optional. If you do not provide it, the tooltip keeps the existing inline render behavior.
44+
45+
When portaling to `document.body`, `positionStrategy="fixed"` is the safest default because it avoids most coordinate-space and overflow issues.
46+
1947
## What should I use instead?
2048

2149
### Replace `data-tooltip-html` with tooltip `children`
@@ -68,5 +96,6 @@ If you previously used HTML strings for multiline tooltips, render JSX instead:
6896
- `data-tooltip-content` is still supported for plain string content
6997
- `content` is still supported for plain string content
7098
- `children` and `render` are now the recommended way to display rich tooltip content
99+
- `portalRoot` is optional and only needed when you want the tooltip rendered outside its default location
71100

72101
Check the current examples for [children](../examples/children.mdx), [render](../examples/render.mdx), and [multiline content](../examples/multiline.mdx).

‎docs/src/pages/benchmark.tsx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -398,7 +398,8 @@ export default function BenchmarkPage(): React.JSX.Element {
398398
size.
399399
</p>
400400
<p className={styles.cardText}>
401-
If you like the project, please give the project a GitHub 🌟
401+
For the full migration surface between v5 and v6, including API changes and new
402+
capabilities, check the <a href="/docs/upgrade-guide/changelog-v5-v6">v5 to v6 changelog</a>.
402403
</p>
403404
</div>
404405
</section>

‎docs/versioned_docs/version-5.x/upgrade-guide/changelog-v5-v6.md‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,46 @@ sidebar_position: 2
44

55
# Changelog V5 -> V6
66

7-
If you are using V5 and want to upgrade to V6, the main change is the removal of the raw HTML string API.
7+
If you are using V5 and want to upgrade to V6, the biggest breaking change is the removal of the raw HTML string API, but it is not the only difference worth checking before migrating.
88

99
## From V5 to V6
1010

11-
V6 keeps the core tooltip behavior from V5, but removes legacy HTML-string entry points so tooltip content stays in React nodes instead of injected markup strings.
11+
V6 keeps the core tooltip behavior from V5, but updates the implementation and API around a few key areas:
12+
13+
- rich tooltip content is rendered through React nodes instead of injected HTML strings
14+
- runtime behavior is lighter and more scalable in larger interfaces
15+
- React 19 is supported while React 16.14+ remains compatible
16+
- optional `portalRoot` support lets you render the tooltip into a custom DOM container when you need tighter control over clipping and overlay layout
1217

1318
## Breaking Changes
1419

1520
- `data-tooltip-html` was removed
1621
- `html` prop was removed
1722
- Raw HTML string examples should now be implemented with `children` or `render`
1823

24+
## New And Updated Capabilities
25+
26+
- `children` and `render` are the preferred way to render rich tooltip content in v6
27+
- `portalRoot` is available when the tooltip should render into a specific DOM node, such as `document.body`
28+
- v6 includes internal runtime improvements that reduce mount cost, memory retention, and shipped bundle size relative to v5
29+
30+
## `portalRoot`
31+
32+
When a layout clips overlays or makes stacking difficult, you can render the tooltip into a separate container:
33+
34+
```jsx
35+
<Tooltip
36+
id="my-tooltip"
37+
content="Hello"
38+
portalRoot={document.body}
39+
positionStrategy="fixed"
40+
/>
41+
```
42+
43+
`portalRoot` is optional. If you do not provide it, the tooltip keeps the existing inline render behavior.
44+
45+
When portaling to `document.body`, `positionStrategy="fixed"` is the safest default because it avoids most coordinate-space and overflow issues.
46+
1947
## What should I use instead?
2048

2149
### Replace `data-tooltip-html` with tooltip `children`
@@ -68,5 +96,6 @@ If you previously used HTML strings for multiline tooltips, render JSX instead:
6896
- `data-tooltip-content` is still supported for plain string content
6997
- `content` is still supported for plain string content
7098
- `children` and `render` are now the recommended way to display rich tooltip content
99+
- `portalRoot` is optional and only needed when you want the tooltip rendered outside its default location
71100

72101
Check the current examples for [children](../examples/children.mdx), [render](../examples/render.mdx), and [multiline content](../examples/multiline.mdx).

0 commit comments

Comments
 (0)