Getting Started

Installation

To download and install react-laag run:

yarn add react-laag

Create a Tooltip component

To get some sense of how react-laag works, we're going to build a simple Tooltip component. Eventually we want a component that looks like:

<Tooltip text="I'm a tooltip!">
  When you hover over this text, a tooltip will appear
</Tooltip>

And here's a working example:
When you hover over this text, a tooltip will appear

Importing the right tools

import { ToggleLayer, useHover } from "react-laag";

Let's go over these, and describe their role.

ToggleLayer - the most important component which takes care of all the heavy lifting (positioning)
useHover - takes care of the logic of when to show the tooltip

The component

We need a component that accepts children and text (the tooltip's text) as props:

import { ToggleLayer, useHover } from "react-laag";

function Tooltip({ children, text }) {
  return (
    // here comes our implementation
  );
}

Connect the tools together

import { ToggleLayer, useHover } from "react-laag";

function Tooltip({ children, text }) {
  // 'isOpen' tells whether we should show the tooltip
  // 'hoverProps' contains event-handlers we should pass to our 'children'
  const [isOpen, hoverProps] = useHover();

  return (
    <ToggleLayer
      // should we show the tooltip?
      isOpen={isOpen}
      // this is the place where we render the tooltip
      renderLayer={({ isOpen, layerProps }) =>
        isOpen && (
          <div
            // provide a 'ref' for calculation purposes
            ref={layerProps.ref}
            style={{
              // forward the 'style' we received from
              // 'renderLayer'
              ...layerProps.style,
              // provide our own styles
              backgroundColor: "black",
              color: "white",
              padding: "2px 8px",
              fontSize: 12,
              borderRadius: 4
            }}
          >
            {text}
          </div>
        )
      }
    >
      {({ triggerRef }) => (
        // wrap the 'children' in a 'span' element
        // and apply the 'triggerRef' and 'hoverProps'
        <span ref={triggerRef} {...hoverProps}>
          {children}
        </span>
      )}
    </ToggleLayer>
  );
}

And there you have it: our custom tooltip component in only a couple of lines 🎉

What about transitions and animations?

react-laag has no opinion on how you should animate your layers and offers you the flexibility of choosing your own method (like react-spring or framer-motion). We do, however, provide a very easy and mimimalistic way for you to animate stuff with the help of the <Transition/> component. It looks like:

<ToggleLayer
  isOpen={isOpen}
  renderLayer={({ isOpen, layerProps }) => (
    // let 'Transition' know when the tooltip should be
    // mounted or unmounted
    <Transition isOpen={isOpen}>
      {(isOpen, onTransitionEnd) => (
        <div
          // provide a 'ref' for calculation purposes
          ref={layerProps.ref}
          // let 'Transition' know when the transition
          // has finished
          onTransitionEnd={onTransitionEnd}
          style={{
            ...layerProps.style,
            // create a fade effect
            transition: "0.2s",
            opacity: isOpen ? 1 : 0
          }}
        >
          {text}
        </div>
      )}
    </Transition>
  )}
/>

Prefer hooks?

No problem! To create a very similar <Tooltip /> component we can utilize the hook variant: useToggleLayer(). Here's the same component, only in 'hook' style:

import { useToggleLayer, useHover } from "react-laag";

function Tooltip({ children, text }) {
  // store a reference to the trigger element
  const triggerRef = React.useRef();

  const [element, toggleLayerProps] = useToggleLayer(
    ({ isOpen, layerProps }) =>
      isOpen && (
        <div
          // provide a 'ref' for calculation purposes
          ref={layerProps.ref}
          style={{
            // forward the 'style' we received from
            // 'renderLayer'
            ...layerProps.style,
            // provide our own styles
            backgroundColor: "black",
            color: "white",
            padding: "2px 8px",
            fontSize: 12,
            borderRadius: 4
          }}
        >
          {text}
        </div>
      ),
    {
      /* options go here */
    }
  );

  const hoverProps = useHover({
    delayEnter: 100,
    delayLeave: 100,
    // instruct useToggleLayer() when to show the layer...
    onShow: () => toggleLayerProps.openFromRef(triggerRef),
    // ...and when to hide it 
    onHide: () => toggleLayerProps.close()
  });

  return (
    <>
      {element}
      <span ref={triggerRef} {...hoverProps}>
        {children}
      </span>
    </>
  );
}

Shorter?!?

Because the combination of useToggleLayer() and useHover() is so common, we've provided a shortcut for you: useTooltip():

import { useTooltip } from "react-laag";

function Tooltip({ children, text }) {
  const [element, triggerProps] = useTooltip(
    ({ isOpen, layerProps }) =>
      isOpen && (
        <div
          ref={layerProps.ref}
          style={{
            ...layerProps.style,
            backgroundColor: "black",
            color: "white",
            padding: "2px 8px",
            fontSize: 12,
            borderRadius: 4
          }}
        >
          {text}
        </div>
      ),
    {
      delayEnter: 100,
      delayLeave: 100
      /* more options go here */
    }
  );

  return (
    <>
      {element}
      <span {...triggerProps}>
        {children}
      </span>
    </>
  );
}

There's much more react-laag can do though. Go to the examples to get some inspiration, or check out the api reference to find out more possibilities.