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.
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.
react >= 0.14react-dom >= 0.14
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.
To include an instance of FlowTip in your component:
import flowtip from 'flowtip/lib/dom';
// Generate a FlowTip™ with the tail and content you want.
const MyFlowTip = flowtip({
tail: toClass(({style, region}) => (
<div className={`flowtip-tail flowtip-tail-${region}`} style={style}/>
)),
content: toClass(({style, region, children}) => (
<div className={`flowtip-root flowtip-root-${region}`} style={style}>
{children}
</div>
)),
});
// Use your new FlowTip™.
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().
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>
)}
/>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.
Default value: false
When set to true, the specified region will become unavailable for the various edge detection algorithms.
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.
Default value: 10
The distance between the tooltip's root (or tip of the tail, see targetOffsetFrom below) and the target's edge.
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.
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).
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).
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.
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.
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.
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.
There are three strategies for detection: flip, rotate and squeeze.
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.
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.
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.
Tool tip'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 refers to the alignment of the pivot relative to the target of the tooltip. See targetAlign and targetAlignOffset.
Root alignment refers to the alignment of the tooltip's root relative to the pivot. See rootAlign and rootAlignOffset.