react-floater

React Floater

Flexible, customizable, and accessible tooltips, popovers, and guided hints for React.

Maintenance Mode: This library is built on Popper.js v2, which is no longer actively maintained. For new projects, we recommend using Floating UI directly.

View the live demo →

Highlights

• Easy to use: Just set the content
• Flexible: Personalize the options to fit your needs
• Type-safe: Full TypeScript support

Usage

npm install react-floater

Import it into your app:

import Floater from 'react-floater';

<Floater content="This is the Floater content">
  <span>click me</span>
</Floater>;

Voilà! A tooltip will appear on click!

Customization & Styling

React Floater is highly customizable. You can:

• Use a custom component for the content via the component prop
  (see WithStyledComponents.ts in the demo).
• Pass a custom arrow using the arrow prop.
• Customize the UI appearance using the styles prop.
  You only need to provide the keys you want to override—defaults will be merged automatically.

<Floater
  content={<div>Custom content <b>with bold!</b></div>}
  placement="right"
  arrow={<MyCustomArrow />}
  styles={{
    container: { backgroundColor: "#222", color: "#fff" },
    arrow: { color: "#222", size: 16, base: 24 },
  }}
>
  <button>Hover or click me</button>
</Floater>

For all available style keys and their default values, see the styles.ts source.

Props

interface PopperModifiers {
  applyStyles?: Partial<ApplyStylesModifier>;
  arrow?: Partial<ArrowModifier>;
  computeStyles?: Partial<ComputeStylesModifier>;
  eventListeners?: Partial<EventListenersModifier>;
  flip?: Partial<FlipModifier>;
  hide?: Partial<HideModifier>;
  offset?: Partial<OffsetModifier>;
  popperOffsets?: Partial<PopperOffsetsModifier>;
  preventOverflow?: Partial<PreventOverflowModifier>;
}

Intended for advanced customization—use with caution.

type 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"
| "center"

interface Styles {
  arrow: CSSProperties & {
    size: number;
    base: number;
  };
  close: CSSProperties;
  container: CSSProperties;
  content: CSSProperties;
  floater: CSSProperties;
  floaterCentered: CSSProperties;
  floaterClosing: CSSProperties;
  floaterOpening: CSSProperties;
  floaterWithAnimation: CSSProperties;
  floaterWithComponent: CSSProperties;
  footer: CSSProperties;
  options: {
    zIndex: number;
  };
  title: CSSProperties;
  wrapper: CSSProperties;
  wrapperPosition: CSSProperties;
}

interface WrapperOptions {
  offset: number; // The distance between the wrapper and the target. It can be a negative value.
  placement: string; // the same options as above, except center
  position: boolean; // Set to true to position the wrapper
}

Modes

React Floater supports several modes for flexible positioning and control:

Default
The Floater is anchored to its child and triggers on event.

<Floater content="This is the Floater content">
  <span>click me</span>
</Floater>

Proxy
The Floater is triggered by the child, but positioned relative to the target.

<div className="App">
  <img src="some-path" />

  <Floater content="This is the Floater content" target=".App img">
    <span>click me</span>
  </Floater>
</div>

Beacon
The Floater wrapper is positioned relative to the target (useful for guided tours or beacons).

<div className="App">
  <img
    src="https://upload.wikimedia.org/wikipedia/commons/2/2d/Google-favicon-2015.png"
    width="100"
    className="my-super-image"
  />

  <Floater
    content="This is the Floater content"
    target=".my-super-image"
    wrapperOptions={{
      offset: -22,
      placement: 'top',
      position: true,
    }}
  >
    <span style={{ color: '#f04', fontSize: 34 }}>◉</span>
  </Floater>
</div>

Controlled
You manage the Floater’s visibility with the open prop - no trigger events are needed. In this mode, you don't even need to have children

<div className="App">
  <img src="some-path" />
  <Floater content="This is the Floater content" open={true} target=".App img" />
</div>