repository·master·Indexed 25 days ago
https://github.com/floating-ui/react-popperOfficial React wrapper for the Popper positioning engine (version 2.3.0). It provides the usePopper hook and components such as Popper, Manager, and Reference to manage the lifecycle and positioning of floating elements. Note: This library is currently in maintenance mode and is a wrapper around @popperjs/core.
This library is currently in maintenance mode. It is a wrapper around @popperjs/core, not the newer @floating-ui/dom.
If you are starting a new project or wish to use the modern Floating UI engine with React, you should use the Floating UI React documentation instead of react-popper.
To use react-popper, you must install both react-popper and its peer dependency @popperjs/core using your preferred package manager.
npm i react-popper @popperjs/coreyarn add react-popper @popperjs/coreIf you are not using a package manager, you can include the UMD library via unpkg. The library is exposed globally as ReactPopper.
<script src="https://unpkg.com/react-popper/dist/index.umd.js"></script># With npm
npm i react-popper @popperjs/core
# With Yarn
yarn add react-popper @popperjs/coreThe Manager component provides a context for managing a shared reference node across multiple Popper instances. This is useful when you have several poppers that should all be positioned relative to the same single reference element.
It exposes two contexts:
ManagerReferenceNodeContext: Provides the current reference element (or null).ManagerReferenceNodeSetterContext: Provides a function to set the reference element.To use it, wrap your Popper components in a <Manager> component. Inside the manager, you can use the setter context to assign a DOM element as the shared reference node.
The options object passed to usePopper accepts standard @popperjs/core options, plus an optional createPopper override.
Supported configuration keys include:
placement: The preferred position of the popper (defaults to 'bottom').strategy: The positioning strategy (defaults to 'absolute').modifiers: An array of Popper modifiers to customize behavior.onFirstUpdate: A callback function triggered on the first update.createPopper: A custom function to create the Popper instance (defaults to @popperjs/core's createPopper).The usePopper hook manages the lifecycle, state, and logic of a Popper instance within a React component. It handles the creation, updating, and destruction of the Popper instance based on the provided reference and popper elements.
referenceElement: The element that acts as the reference for the popper (can be a DOM Element or a VirtualElement).popperElement: The DOM element that will be positioned by Popper.options: An optional configuration object of type Options (extending @popperjs/core options).The hook returns an object containing:
state: The current Popper state (if an instance exists).styles: An object containing the computed CSS styles for the popper elements.attributes: An object containing the computed attributes for the popper elements.update: A function to manually trigger a Popper update.forceUpdate: A function to force a Popper update.The Reference component is used to identify the element that serves as the reference for a floating UI element (like a tooltip or popover). It must be used as a child of a Manager component.
It uses a render prop pattern: the children prop is a function that receives an object containing a ref. You must pass this ref to the DOM element you want to act as the reference.
If you need to access the reference node directly in your own code, you can provide an innerRef prop.
The Popper component is the primary entry point for managing Popper positioning in React. It uses a render-prop pattern via its children prop. The children function receives an object containing references to the popper and arrow elements, their styles, and methods to control updates.
Key Props:
children: A function that receives PopperChildrenProps. This is required to render the popper and arrow elements.placement: The initial positioning of the popper (e.g., 'bottom', 'top'). Defaults to 'bottom'.strategy: The positioning strategy ('absolute' or 'fixed'). Defaults to 'absolute'.modifiers: An array of Popper modifiers to customize behavior.referenceElement: An optional HTMLElement or VirtualElement to use as the reference. If not provided, it uses the node from the ManagerReferenceNodeContext.onFirstUpdate: A callback function triggered after the first positioning update.innerRef: An optional ref to attach to the popper element.PopperChildrenProps (passed to children function):
ref: A function to set the popper element ref.style: The CSS styles for the popper element.placement: The current placement of the popper.isReferenceHidden: Boolean indicating if the reference is hidden (via the hide modifier).hasPopperEscaped: Boolean indicating if the popper has escaped the viewport (via the hide modifier).update: A function that returns a Promise to trigger a repositioning.forceUpdate: A function to force a repositioning.arrowProps: An object containing ref and style for the arrow element.When using the Popper component, the children function provides the necessary tools to render the popper and its arrow.
Available properties in the render function:
| Property | Type | Description |
|---|---|---|
ref | Ref | Function to assign the popper element ref. |
style | CSSStyleDeclaration | Styles for the popper element (position, offset, etc.). |
placement | Placement | The current placement of the popper. |
isReferenceHidden | ?boolean | Whether the reference is hidden (from hide modifier). |
hasPopperEscaped | ?boolean | Whether the popper has escaped the viewport (from hide modifier). |
update | () => Promise<null | $Shape<State>> | Triggers a repositioning update. |
forceUpdate | () => void | Forces a repositioning update. |
arrowProps | PopperArrowProps | Object containing ref and style for the arrow element. |
The Popper component accepts the following configuration properties:
| Prop | Type | Description |
|---|---|---|
children | PopperChildren | Required. A render-prop function providing popper/arrow refs and styles. |
innerRef | Ref | Optional ref to attach to the popper element. |
modifiers | Modifiers | Array of Popper modifiers. |
placement | Placement | The preferred placement of the popper. Defaults to 'bottom'. |
strategy | PositioningStrategy | 'absolute' or 'fixed'. Defaults to 'absolute'. |
referenceElement | ReferenceElement | An HTMLElement or VirtualElement. If omitted, uses context. |
onFirstUpdate | ($Shape<State>) => void | Callback called after the first positioning update. |
The object passed to the children render prop contains:
ref: The function used to register the reference node with the Manager.Popper component is a public component used to render the floating element.The following types are exported for use with the Popper component:
PopperPropsPopperChildrenPropsPopperArrowProps