FlowTip

A flexible, adaptable and easy to use tooltip component for React.js

Looking for the non-React.js version? It's in the legacy branch.

At its core, FlowTip is a set of calculations that ensure.

Demo

See the demo from the legacy branch. The code sample on the side doesn't apply to the current React version but the behaviour is basically the same.

Peer Dependencies

• react >= 0.14
• react-dom >= 0.14

Glossaries

The documentation and source of this library refers to several terms that may require clarification:

Parent: The element bounding the tooltip.

Content: The container element for the tooltip's content.

Tail: The tail of the tooltip. It's usually visualized as a pointy "nub" of sort.

Target: The target is the thing the tooltip points to.

Region: There are four different regions a tooltip could be in at any given time. The four regions are "top", "bottom", "left" and "right". Region is described relative to the target of the tooltip. For example, region "top" means the tooltip would appear above the target, and region "right" means the tooltip would appear to the right side of the target.

Pivot: The pivot is a imaginary line that is aligned to the target and the tooltip's root is then in term aligned to the pivot.

Anchor: The element from which the tooltips position is referenced.

Basic Usage

To include an instance of FlowTip in your component:

import flowtip from 'flowtip/lib/dom';

// Define the FlowTip content component
const ContentComponent = ({style, region, children}) => (
  <div className={`flowtip-root flowtip-root-${region}`} style={style}>
    {children}
  </div>
);

// Define the FlowTip tail component
const TailComponent = ({style, region}) => (
  <div className={`flowtip-tail flowtip-tail-${region}`} style={style} />
);

// Generate a FlowTip™ component with the content and tail components.
const MyFlowTip = flowtip(ContentComponent, TailComponent);

// Render the FlowTip™ component.
const target = {
  top: 5,
  left: 5,
  width: 100,
  height: 100,
};

<MyFlowTip target={target}>
  <b>Holy Shit!</b>
  <br />
  FlowTip as React Component
</FlowTip>

The target property specifies the position and dimension of the tooltip's target as calculated by getBoundingClientRect().

Advanced Usage

The primary FlowTip component is essentially a stateless function that computes where the tooltip should be displayed (based on the bounding boxes you pass to it) and then passes that information down to its children. It's quite possible to build tooltips for platforms other than just the browser.

The DOM implementation takes care of computing all the values except target for you.

import FlowTip from 'flowtip';

<FlowTip
  tail={...}
  content={...}
  target={...}
  parent={...}
  anchor={...}
  children={({content, tail}) => (
    <div style={{
      position: "absolute",
      left: content.left,
      top: content.top,
    }}>
      Hello.
      <div style={{
        position: "absolute",
        left: tail.left,
        top: tail.top,
      }}/>
    </div>
  )}
/>

FlowTip Properties

region: String

Default value: top

The preferred region in which the tooltip will appear at first relative to its target. Possibly values are: top, bottom, left and right.

topDisabled, bottomDisabled, leftDisabled and rightDisabled: Boolean

Default value: false

When set to true, the specified region will become unavailable for the various edge detection algorithms.

hideInDisabledRegions: Boolean

Default value: false

When set to true, and when the only suitable regions for the tooltip are disabled, the tooltip will be hidden. When set to false, and when the only suitable regions for the tooltip are disabled, the tooltip will be placed in its original region.

targetOffset: Integer

Default value: 10

The distance between the tooltip's root (or tip of the tail, see targetOffsetFrom below) and the target's edge.

targetOffsetFrom: String

Default value: root

Possible values are root and tail. When set to root, targetOffset will be calculated against the edge of the tooltip's root; When set to tail, targetOffset will be calculated against the tip of the tail.

edgeOffset: Integer

Default value: 30

The distance between the tooltip's root's edge and the edge of the boundary representative the tooltip's appendTo element. When this distance is smaller than edgeOffset, edge detection will place the tooltip in an opposite region (i.e. flipping the tooltip).

rotationOffset: Integer

Default value: 30

The distance between the target's edge and the edge of the boundary representative the tooltip's appendTo element. When this distance is smaller than rotationOffset, edge detection will place the tooltip in an adjacent region (i.e. rotating the tooltip).

targetAlign: String

Default value: center

Possible values are center and edge. When set to center, the pivot will be center aligned against the target. When set to edge, one of the pivot's edge will be aligned against the pivot. See targetAlignOffset for the exact mechanics of the two values. This value can also be specified on a per-region basis via [top|bottom|left|right]TargetAlign, and if a region's specific value is absence, the value from targetAlign will be used.

targetAlignOffset: Integer

Default value: 0

If targetAlign is set to center, this value controls the clockwise distance from the center of the target the pivot will shift. When this value is positive, the pivot will shift clockwise, and counter-clockwise when this value is negative.

If targetAlign is set to edge, the pivot will shift away from one of the target's edges. When this value is positive, the clockwise edge will be used, and the counter-clockwise edge will be used when this value is negative. The absolute value of this value controls the amount of shifting.

rootAlign: String

Default value: center

Possible values are center and edge. When set to center, the tooltip's root will be center aligned against the pivot. When set to edge, one of the tooltip's root's edge will be aligned against the pivot. See rootAlignOffset for the exact mechanics of the two values. This value can also be specified on a per-region basis via [top|bottom|left|right]RootAlign, and if a region's specific value is absence, the value from rootAlign will be used.

rootAlignOffset: Integer

Default value: 0

If rootAlign is set to center, this value controls the clockwise distance from the pivot the tooltip's root will shift. When this value is positive, the root will shift clockwise, and counter-clockwise when this value is negative.

If rootAlign is set to edge, one of the tooltip's root's edge will be aligned against the pivot. When this value is positive, the clockwise edge will be used, and the counter-clockwise edge will be used when this value is negative. The absolute value of this value controls the amount of shifting.

Edge Detection

There are three strategies for detection: flip, rotate and squeeze.

Flip

The tooltip will be flipped when the root of the tooltip gets too close to the edge of the boundary. Adjust edgeOffset to control the amount of space allowed. The tooltip will be flipped horizontally when in the left and right regions, and vertically when in the top and bottom regions.

Rotate

The tooltip will be rotated to an adjacent region if the target gets too close to the edge of the boundary. Adjust rotationOffset to control the amount of space allowed. For example, the tooltip will be rotated to the top region if the tooltip is currently in the left or right region, and the target gets too close to the bottom edge of the boundary.

Squeeze

The tooltip will be squeezed to an adjacent region if the root of the tooltip gets too close to the edge of the boundary on both sides. For example, if the tooltip is in left or right region, and neither region has enough space, the tooltip will be squeezed to the top region.

Alignments

Tooltip's alignments are divided into root alignment and target alignment, each with a corresponding offset attribute that controls the direction of the alignment and offset amount.

Target Alignment

Target alignment refers to the alignment of the pivot relative to the target of the tooltip. See targetAlign and targetAlignOffset.

Root Alignment

Root alignment refers to the alignment of the tooltip's root relative to the pivot. See rootAlign and rootAlignOffset.

Clamping

By default the tooltip is "clamped" to its parent. Meaning even if the target leaves the viewport, the tooltip would never leave the viewport. The clamping behaviour can be controlled via the clamp property.

When clamp is true, the flyout will always remains in the parent even if the target is out of the parent.

When clamp is false, the flyout will always attatch itself to the target, even if it’s outside the parent, but it will make a best effort to be in the parent.