Skip to content

Commit f53d1c9

Browse files
docs: imperative mode
1 parent d07bc9b commit f53d1c9

File tree

2 files changed

+181
-0
lines changed

2 files changed

+181
-0
lines changed
Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Imperative mode
6+
7+
Using the ReactTooltip imperative mode to control the tooltip programatically.
8+
9+
import { useRef } from 'react';
10+
import { Tooltip } from 'react-tooltip'
11+
12+
export const TooltipAnchor = ({ children, id, ...rest }) => {
13+
return (
14+
<span
15+
id={id}
16+
style={{
17+
display: 'flex',
18+
justifyContent: 'center',
19+
margin: 'auto',
20+
alignItems: 'center',
21+
width: '60px',
22+
height: '60px',
23+
borderRadius: '60px',
24+
color: '#222',
25+
background: 'rgba(255, 255, 255, 1)',
26+
cursor: 'pointer',
27+
boxShadow: '3px 4px 3px rgba(0, 0, 0, 0.5)',
28+
border: '1px solid #333',
29+
}}
30+
{...rest}
31+
>
32+
{children}
33+
</span>
34+
)
35+
}
36+
37+
### Basic usage
38+
39+
A ref object created with `React.useRef()` can passed to the `ref` tooltip prop.
40+
It allows you to expose internal state variables (read-only), and also to control the tooltip programatically.
41+
42+
The relevant interfaces are as follows:
43+
44+
```ts
45+
interface TooltipImperativeOpenOptions {
46+
anchorSelect?: string
47+
position?: IPosition
48+
place?: PlacesType
49+
/**
50+
* In practice, `ChildrenType` -> `React.ReactNode`
51+
*/
52+
content?: ChildrenType
53+
}
54+
55+
interface TooltipImperativeProps {
56+
open: (options?: TooltipImperativeOpenOptions) => void
57+
close: () => void
58+
/**
59+
* @readonly
60+
*/
61+
activeAnchor: HTMLElement | null
62+
/**
63+
* @readonly
64+
*/
65+
place: PlacesType
66+
/**
67+
* @readonly
68+
*/
69+
isOpen: boolean
70+
}
71+
```
72+
73+
- `open()` opens the tooltip programatically. All of the function arguments are optional
74+
- `anchorSelect` overrides the selector currently in use. Ideally, it should match only one element (e.g. `#some-element`)
75+
- `position` overrides the tooltip position. Behaves the same way as the `position` tooltip prop
76+
- `place` overrides the tooltip placement relative to the anchor. Behaves the same was the `place` tooltip prop
77+
- `content` overrides the tooltip content
78+
- `close()` closes the tooltip programatically
79+
80+
:::note
81+
82+
These are read-only. Updating their values has no effect on the tooltip.
83+
84+
:::
85+
86+
- `activeAnchor` is a reference to the current anchor element
87+
- `place` is the current tooltip placement relative to the anchor element. Can differ from the `place` tooltip prop if the tooltip is close to the edges of its container
88+
- `isOpen` indicates whether the tooltip is currently being shown or not
89+
90+
:::info
91+
92+
The imperative methods <b>can</b> be applied alongside regular tooltip usage. For example, you could use just `close()` to close a regular tooltip after an API request is finished.
93+
94+
:::
95+
96+
```jsx
97+
import { useRef } from 'react';
98+
import { Tooltip, TooltipImperativeProps } from 'react-tooltip';
99+
100+
const tooltipRef1 = useRef<TooltipImperativeProps>(null)
101+
const tooltipRef2 = useRef<TooltipImperativeProps>(null)
102+
103+
<a id="my-element">
104+
◕‿‿◕
105+
</a>
106+
<button
107+
onClick={() => {
108+
tooltipRef1.current?.open({
109+
anchorSelect: '#my-element',
110+
content: 'Hello world!',
111+
})
112+
tooltipRef2.current?.open({
113+
position: {
114+
x: Math.random() * 500,
115+
y: Math.random() * 300,
116+
},
117+
place: 'bottom',
118+
content: 'Where am I? 😕😕',
119+
})
120+
}}
121+
>
122+
Open
123+
</button>
124+
<button
125+
onClick={() => {
126+
tooltipRef1.current?.close()
127+
tooltipRef2.current?.close()
128+
}}
129+
>
130+
Close
131+
</button>
132+
<Tooltip ref={tooltipRef1} />
133+
<Tooltip ref={tooltipRef2} />
134+
```
135+
136+
export const ImperativeModeExample = () => {
137+
const tooltipRef1 = useRef(null)
138+
const tooltipRef2 = useRef(null)
139+
return (
140+
<>
141+
<TooltipAnchor id="my-element">
142+
◕‿‿◕
143+
</TooltipAnchor>
144+
<div style={{ display: 'flex', flexDirection: 'row', gap: '5px' }}>
145+
<button
146+
onClick={() => {
147+
tooltipRef1.current?.open({
148+
anchorSelect: '#my-element',
149+
content: 'Hello world!',
150+
})
151+
tooltipRef2.current?.open({
152+
position: {
153+
x: 300 + Math.random() * 500,
154+
y: 300 + Math.random() * 300,
155+
},
156+
place: 'bottom',
157+
content: 'Where am I? 😕😕',
158+
})
159+
}}
160+
>
161+
Open
162+
</button>
163+
<button
164+
onClick={() => {
165+
tooltipRef1.current?.close()
166+
tooltipRef2.current?.close()
167+
}}
168+
>
169+
Close
170+
</button>
171+
</div>
172+
<Tooltip ref={tooltipRef1} />
173+
<Tooltip ref={tooltipRef2} />
174+
</>
175+
)
176+
}
177+
178+
<div style={{ display: 'flex', flexDirection: 'column', gap: '10px', width: 'fit-content', margin: 'auto' }}>
179+
<ImperativeModeExample />
180+
</div>

docs/docs/options.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ import { Tooltip } from 'react-tooltip';
8989

9090
| name | type | required | default | values | description |
9191
| ----------------------- | -------------------------------------- | -------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
92+
| `ref` | Tooltip reference | no | | `React.useRef` | Reference object which exposes internal state, and some methods for manually controlling the tooltip. See [the examples](./examples/imperative-mode.mdx). |
9293
| `className` | `string` | no | | | Class name to customize tooltip element. You can also use the default class `react-tooltip` which is set internally |
9394
| `classNameArrow` | `string` | no | | | Class name to customize tooltip arrow element. You can also use the default class `react-tooltip-arrow` which is set internally |
9495
| `content` | `string` | no | | | Content to de displayed in tooltip (`html` prop is priorized over `content`) |

0 commit comments

Comments
 (0)