react-popper

`react-popper` is a React wrapper library for the powerful positioning engine, Popper.js. Popper.js is a lightweight, dependency-free JavaScript library designed to position UI elements (like tooltips, popovers, dropdowns, and context menus) adjacent to a "reference" element while ensuring they stay within the viewport and adjust their position intelligently to avoid obscuring content.

`react-popper` brings the full power of Popper.js into the React ecosystem by providing components and hooks that simplify its integration. Instead of manually managing DOM nodes and Popper.js instances, developers can use `react-popper`'s declarative API to connect a reference element with a popper element (the element being positioned).

Key features and concepts of `react-popper` include:

1. `usePopper` Hook: The primary way to use `react-popper` in functional components. It takes a reference element and a popper element, returning state and functions to manage their positioning.
2. Reference Element: The UI element to which the popper (e.g., tooltip) is anchored. `react-popper` needs a DOM reference to this element.
3. Popper Element: The UI element that needs to be positioned relative to the reference. This is typically the tooltip, popover, or dropdown itself.
4. Placement: Defines the initial preferred position of the popper (e.g., `'top'`, `'bottom-start'`, `'right'`). Popper.js intelligently "flips" the placement if the preferred position would cause the popper to go out of bounds.
5. Modifiers: A powerful concept from Popper.js that allows customization of positioning behavior. Common modifiers include:
* `offset`: Adds a pixel offset between the reference and the popper.
* `preventOverflow`: Ensures the popper stays within the viewport.
* `flip`: Allows the popper to "flip" to the opposite side if it overflows.
* `arrow`: Positions an arrow element correctly on the popper.
6. `styles` and `attributes`: The `usePopper` hook provides computed `styles` and `attributes` that need to be applied directly to the popper and arrow elements for correct positioning. These are dynamic and updated on scroll, resize, or other layout changes.

By abstracting away the low-level DOM manipulations, `react-popper` allows React developers to focus on their component logic and UI, while ensuring robust and performant positioning for dynamic elements. It's an essential library for building rich, interactive user interfaces with complex overlay components.

Example Code

import React, { useState, useRef, useCallback } from 'react';
import { usePopper } from 'react-popper';

function TooltipExample() {
  const [isTooltipVisible, setIsTooltipVisible] = useState(false);

  // Refs for the reference element (button) and the popper element (tooltip)
  const [referenceElement, setReferenceElement] = useState(null);
  const [popperElement, setPopperElement] = useState(null);

  // Hook to connect the reference and popper, and get positioning state
  const { styles, attributes } = usePopper(referenceElement, popperElement, {
    placement: 'bottom', // Preferred placement: bottom
    modifiers: [
      {
        name: 'offset', // Add an offset modifier
        options: {
          offset: [0, 8], // 0px along the reference, 8px away from the reference
        },
      },
      {
        name: 'flip', // Allow the tooltip to flip if it overflows
        options: {
          padding: 8, // Padding around the viewport to consider for flipping
        },
      },
      {
        name: 'preventOverflow', // Prevent the tooltip from overflowing the viewport
        options: {
          padding: 8,
        },
      },
    ],
  });

  const showTooltip = useCallback(() => setIsTooltipVisible(true), []);
  const hideTooltip = useCallback(() => setIsTooltipVisible(false), []);

  return (
    <div style={{ padding: '100px', display: 'flex', justifyContent: 'center', alignItems: 'center', height: '100vh', flexDirection: 'column' }}>
      <h1>React Popper Tooltip Example</h1>
      <button
        type="button"
        ref={setReferenceElement} // Assign reference element
        onMouseEnter={showTooltip}
        onMouseLeave={hideTooltip}
        style={{
          padding: '10px 20px',
          fontSize: '16px',
          cursor: 'pointer',
          backgroundColor: '#007bff',
          color: 'white',
          border: 'none',
          borderRadius: '4px',
          marginBottom: '20px',
        }}
      >
        Hover me
      </button>

      {isTooltipVisible && (
        <div
          ref={setPopperElement} // Assign popper element
          style={{
            ...styles.popper, // Apply computed styles to the popper
            backgroundColor: '#333',
            color: 'white',
            padding: '8px 12px',
            borderRadius: '4px',
            fontSize: '14px',
            zIndex: 1000,
            boxShadow: '0 2px 10px rgba(0,0,0,0.2)',
          }}
          {...attributes.popper} // Apply computed attributes to the popper
        >
          This is a React Popper tooltip!
        </div>
      )}

      <p style={{ marginTop: '50px', maxWidth: '400px', textAlign: 'center' }}>
        This example demonstrates how to use `react-popper` to create a simple tooltip that appears when hovering over a button.
        The `usePopper` hook automatically handles positioning and ensures the tooltip stays visible within the viewport.
      </p>
    </div>
  );
}

export default TooltipExample;

Example Code

Related Topics