0
# React Popper
1
2
React Popper is the official React wrapper around Popper.js positioning engine. It provides React components and hooks for creating tooltips, popovers, dropdowns, and other floating elements with precise positioning. The library offers both component-based (Manager, Reference, Popper) and hook-based (usePopper) approaches for maximum flexibility.
3
4
## Package Information
5
6
- **Package Name**: react-popper
7
- **Package Type**: npm
8
- **Language**: JavaScript with Flow types and TypeScript definitions
9
- **Installation**: `npm install react-popper @popperjs/core`
10
11
**Note**: `@popperjs/core` is a required peer dependency.
12
13
## Core Imports
14
15
```typescript
16
import { Manager, Reference, Popper, usePopper } from "react-popper";
17
import type {
18
ManagerProps,
19
ReferenceProps,
20
ReferenceChildrenProps,
21
PopperProps,
22
PopperChildrenProps,
23
PopperArrowProps
24
} from "react-popper";
25
```
26
27
For CommonJS:
28
29
```javascript
30
const { Manager, Reference, Popper, usePopper } = require("react-popper");
31
```
32
33
## Basic Usage
34
35
### Component-Based Approach
36
37
```tsx
38
import React from "react";
39
import { Manager, Reference, Popper } from "react-popper";
40
41
function Tooltip() {
42
const [showTooltip, setShowTooltip] = React.useState(false);
43
44
return (
45
<Manager>
46
<Reference>
47
{({ ref }) => (
48
<button
49
ref={ref}
50
onMouseEnter={() => setShowTooltip(true)}
51
onMouseLeave={() => setShowTooltip(false)}
52
>
53
Hover me
54
</button>
55
)}
56
</Reference>
57
{showTooltip && (
58
<Popper placement="top">
59
{({ ref, style, placement }) => (
60
<div ref={ref} style={style} data-placement={placement}>
61
Tooltip content
62
</div>
63
)}
64
</Popper>
65
)}
66
</Manager>
67
);
68
}
69
```
70
71
### Hook-Based Approach
72
73
```tsx
74
import React from "react";
75
import { usePopper } from "react-popper";
76
77
function HookTooltip() {
78
const [referenceElement, setReferenceElement] = React.useState(null);
79
const [popperElement, setPopperElement] = React.useState(null);
80
const { styles, attributes } = usePopper(referenceElement, popperElement, {
81
placement: "top",
82
});
83
84
return (
85
<>
86
<button ref={setReferenceElement}>Reference element</button>
87
<div ref={setPopperElement} style={styles.popper} {...attributes.popper}>
88
Popper element
89
</div>
90
</>
91
);
92
}
93
```
94
95
## Architecture
96
97
React Popper is built around several key components:
98
99
- **Manager Component**: Context provider that coordinates between Reference and Popper components
100
- **Reference Component**: Marks reference elements and provides positioning context
101
- **Popper Component**: Creates positioned elements with advanced configuration options
102
- **usePopper Hook**: Low-level hook for programmatic control over Popper instances
103
- **Context System**: React contexts for sharing reference element state between components
104
105
## Capabilities
106
107
### Context Management
108
109
Provides context management for coordinating reference and popper elements in component-based usage patterns.
110
111
```typescript { .api }
112
function Manager({ children }: ManagerProps): React.Node;
113
114
interface ManagerProps {
115
children: React.ReactNode;
116
}
117
```
118
119
[Context Management](./context-management.md)
120
121
### Reference Element Handling
122
123
Handles reference element registration and provides render props for attaching refs to DOM elements.
124
125
```typescript { .api }
126
function Reference({ children, innerRef }: ReferenceProps): React.Node;
127
128
interface ReferenceProps {
129
children: (props: ReferenceChildrenProps) => React.ReactNode;
130
innerRef?: React.Ref<any>;
131
}
132
133
interface ReferenceChildrenProps {
134
ref: React.Ref<any>;
135
}
136
```
137
138
[Reference Handling](./reference-handling.md)
139
140
### Positioned Element Creation
141
142
Creates positioned popper elements with comprehensive configuration options and render props providing positioning data.
143
144
```typescript { .api }
145
function Popper<Modifiers>({
146
children,
147
innerRef,
148
modifiers,
149
placement,
150
strategy,
151
referenceElement,
152
onFirstUpdate,
153
}: PopperProps<Modifiers>): React.Node;
154
155
interface PopperProps<Modifiers> {
156
children: (props: PopperChildrenProps) => React.ReactNode;
157
innerRef?: React.Ref<any>;
158
modifiers?: ReadonlyArray<Modifier<Modifiers>>;
159
placement?: PopperJS.Placement;
160
strategy?: PopperJS.PositioningStrategy;
161
referenceElement?: HTMLElement | PopperJS.VirtualElement;
162
onFirstUpdate?: (state: Partial<PopperJS.State>) => void;
163
}
164
165
interface PopperChildrenProps {
166
ref: React.Ref<any>;
167
style: React.CSSProperties;
168
placement: PopperJS.Placement;
169
isReferenceHidden?: boolean;
170
hasPopperEscaped?: boolean;
171
update: () => Promise<null | Partial<PopperJS.State>>;
172
forceUpdate: () => Partial<PopperJS.State>;
173
arrowProps: PopperArrowProps;
174
}
175
176
interface PopperArrowProps {
177
ref: React.Ref<any>;
178
style: React.CSSProperties;
179
}
180
```
181
182
[Positioned Elements](./positioned-elements.md)
183
184
### Programmatic Hook Interface
185
186
Provides low-level programmatic control over Popper instances without component wrappers.
187
188
```typescript { .api }
189
function usePopper<Modifiers>(
190
referenceElement?: Element | PopperJS.VirtualElement | null,
191
popperElement?: HTMLElement | null,
192
options?: Omit<Partial<PopperJS.Options>, 'modifiers'> & {
193
createPopper?: typeof PopperJS.createPopper;
194
modifiers?: ReadonlyArray<Modifier<Modifiers>>;
195
}
196
): {
197
styles: { [key: string]: React.CSSProperties };
198
attributes: { [key: string]: { [key: string]: string } | undefined };
199
state: PopperJS.State | null;
200
update: PopperJS.Instance['update'] | null;
201
forceUpdate: PopperJS.Instance['forceUpdate'] | null;
202
};
203
```
204
205
[Hook Interface](./hook-interface.md)
206
207
## Common Types
208
209
```typescript { .api }
210
// Utility type for union intersections
211
type UnionWhere<U, M> = U extends M ? U : never;
212
213
// Modifier types for configuration
214
type StrictModifierNames = NonNullable<PopperJS.StrictModifiers['name']>;
215
216
type StrictModifier<
217
Name extends StrictModifierNames = StrictModifierNames
218
> = UnionWhere<PopperJS.StrictModifiers, { name?: Name }>;
219
220
type Modifier<
221
Name,
222
Options extends object = object
223
> = Name extends StrictModifierNames
224
? StrictModifier<Name>
225
: Partial<PopperJS.Modifier<Name, Options>>;
226
227
// Ref handling types
228
type RefHandler = (ref: HTMLElement | null) => void;
229
```