npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-popper-tooltip

v4.4.2

Published

React tooltip library built around react-popper

Downloads

3,296,479

Readme

react-popper-tooltip

npm version npm downloads codecov

A React hook to effortlessly build smart tooltips. Based on react-popper and popper.js.

NOTE

  • This is the documentation for 4.x which introduced the usePopperTooltip hook.
  • If you're looking for the render prop version, see 3.x docs.
  • If you're looking to upgrade from 3.x render prop to 4.x hook, please refer to our migration guide.

Examples

Installation

You can install react-popper-tooltip with npm or yarn.

npm i react-popper-tooltip
# or
yarn add react-popper-tooltip

Quick start

This example illustrates how to create a minimal tooltip with default settings and using our default CSS file.

import * as React from 'react';
import { usePopperTooltip } from 'react-popper-tooltip';
import 'react-popper-tooltip/dist/styles.css';

function App() {
  const {
    getArrowProps,
    getTooltipProps,
    setTooltipRef,
    setTriggerRef,
    visible,
  } = usePopperTooltip();

  return (
    <div className="App">
      <button type="button" ref={setTriggerRef}>
        Trigger
      </button>
      {visible && (
        <div
          ref={setTooltipRef}
          {...getTooltipProps({ className: 'tooltip-container' })}
        >
          <div {...getArrowProps({ className: 'tooltip-arrow' })} />
          Tooltip
        </div>
      )}
    </div>
  );
}

render(<App />, document.getElementById('root'));

Styling

With react-popper-tooltip, you can use CSS, LESS, SASS, or any CSS-in-JS library you're already using in your project. However, we do provide a minimal CSS-file file you can use for a quick start or as a reference to create your own tooltip styles.

Import react-popper-tooltip/dist/styles.css to import it into your project. Add classes tooltip-container and tooltip-arrow to the tooltip container and arrow element accordingly.

While the tooltip is being displayed, you have access to some attributes on the tooltip container. You can use them in your CSS in specific scenarios.

  • data-popper-placement: contains the current tooltip placement. You can use it to properly offset and display the arrow element (e.g., if the tooltip is displayed on the right, the arrow should point to the left and vice versa).

  • data-popper-reference-hidden: set to true when the trigger element is fully clipped and hidden from view, which causes the tooltip to appear to be attached to nothing. Set to false otherwise.

  • data-popper-escaped: set to true when the tooltip escapes the trigger element's boundary (and so it appears detached). Set to false otherwise.

  • data-popper-interactive: contains the current interactive option value.

API reference

usePopperTooltip

const {
  getArrowProps,
  getTooltipProps,
  setTooltipRef,
  setTriggerRef,
  tooltipRef,
  triggerRef,
  visible,
  ...popperProps
} = usePopperTooltip(
  {
    closeOnOutsideClick,
    closeOnTriggerHidden,
    defaultVisible,
    delayHide,
    delayShow,
    followCursor,
    interactive,
    mutationObserverOptions,
    offset,
    onVisibleChange,
    placement,
    trigger,
    visible,
  },
  popperOptions
);

Options

  • closeOnOutsideClick: boolean, defaults to true

If true, closes the tooltip when user clicks outside the trigger element.

  • closeOnTriggerHidden: boolean, defaults to false

Whether to close the tooltip when its trigger is out of boundary.

  • delayHide: number, defaults to 0

Delay in hiding the tooltip (ms).

  • delayShow: number, defaults to 0

Delay in showing the tooltip (ms).

  • defaultVisible: boolean, defaults to false

The initial visibility state of the tooltip when the hook is initialized.

  • followCursor: boolean, defaults to false

If true, the tooltip will stick to the cursor position. You would probably want to use this option with hover trigger.

  • mutationObserverOptions: MutationObserverInit | null, defaults to { attributes: true, childList: true, subtree: true }

Options to MutationObserver , used internally for updating tooltip position based on its DOM changes. When the tooltip is visible and its content changes, it automatically repositions itself. In some cases you may need to change which parameters to observe or opt-out of tracking the changes at all.

  • offset: [number, number], defaults to [0, 6]

This is a shorthand for popperOptions.modifiers offset modifier option. The default value means the tooltip will be placed 6px away from the trigger element (to reserve enough space for the arrow element).

We use this default value to match the size of the arrow element from our default CSS file. Feel free to change it if you are using your own styles.

See offset modifier docs.

popperOptions takes precedence over this option.

  • onVisibleChange: (state: boolean) => void

Called with the tooltip state, when the visibility of the tooltip changes.

  • trigger: TriggerType | TriggerType[] | null, where TriggerType = 'click' | 'right-click' | 'hover' | 'focus', defaults to hover

Event or events that trigger the tooltip. Use null if you want to disable all events. It's useful in cases when you control the state of the tooltip.

  • visible: boolean

The visibility state of the tooltip. Use this prop if you want to control the state of the tooltip. Note that delayShow and delayHide are not used if the tooltip is controlled. You have to apply delay on your external state.

react-popper-tooltip manages its own state internally and calls onVisibleChange handler with any relevant changes.

However, if more control is needed, you can pass this prop, and the state becomes controlled. As soon as it's not undefined, internally, react-popper-tooltip will determine its state based on your prop's value rather than its own internal state.

  • placement: 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'right' | 'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end';

The preferred placement of the tooltip. This is an alias for popperOptions.placement option.

popperOptions takes precedence over this option.

  • interactive: boolean, defaults to false

If true, hovering the tooltip will keep it open. Normally, if you trigger the tooltip on hover event, the tooltip closes when the mouse cursor moves out of the trigger element. If it moves to the tooltip element, the tooltip stays open. It's useful if you want to allow your users to interact with the tooltip's content (select and copy text, click a link, etc.). In this case you might want to increase delayHide value to give the user more time to react.

  • popperOptions: { placement, modifiers, strategy, onFirstUpdate }

These options passed directly to the underlying usePopper hook. See https://popper.js.org/docs/v2/constructors/#options.

Keep in mind, if you set placement or any modifiers here, it replaces offset and placement options above. They won't be merged into the final object. You have to add offset modifier along with others here to make it work.

Returns

  • triggerRef: HTMLElement | null

The trigger DOM element ref.

  • tooltipRef: HTMLElement | null

The tooltip DOM element ref.

  • setTooltipRef: (HTMLElement | null) => void | null

A tooltip callback ref. Must be assigned to the tooltip's ref prop.

  • setTriggerRef: (HTMLElement | null) => void | null

A trigger callback ref. Must be assigned to the trigger's ref prop.

  • visible: boolean

The current visibility state of the tooltip. Use it to display or hide the tooltip.

  • getArrowProps: (props) => mergedProps

This function merges your props and the internal props of the arrow element. We recommend passing all your props to that function rather than applying them on the element directly to avoid your props being overridden or overriding the internal props.

It returns the merged props that you need to pass to the arrow element.

  • getTooltipProps: (props) => mergedProps

This function merges your props and the internal props of the tooltip element. We recommend passing all your props to that function rather than applying them on the element directly to avoid your props being overridden or overriding the internal props.

It returns the merged props that you need to pass to tooltip element.

  • popperProps: { update, forceUpdate, state }

Some props returned by the underlying usePopper hook. See https://popper.js.org/react-popper/v2/hook.

This doesn't include styles and attributes props. They are included into getArrowProps and getTooltipProps prop getters.