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
```