react-tipsy
v0.6.2
Published
A React component that allows you to easily create simple tooltips.
Downloads
407
Maintainers
Readme
react-tipsy
A React component that allows you to easily create simple tooltips.
Inspired by Bootstrap's 3.x jQuery tooltips,
which drew its inspiration from the jQuery.tipsy plugin written by Jason Frame, react-tipsy
is a
simple React component that allows you to easily add tooltips to any React element.
Like bootstrap's tooltip plugin, react-tipsy does not rely on images.
Installation
The easiest way to use react-tipsy
is to install it from NPM and include it in your React build process (using Webpack, etc).
npm install react-tipsy --save
You can also use the standalone build by including dist/react-tipsy.min.js
and dist/react-tipsy.css
in your page. If you do this, make sure you already included the following dependencies:
Usage
react-tipsy
is a React component that wraps a single React element.
var Tipsy = require('react-tipsy');
<Tipsy content="Hello, world!" placement="bottom" trigger="hover focus touch" className="my-tooltip">
<h1>Welcome!</h1>
</Tipsy>
The children
property must be a React Element. (required)
The content
property can be a any mountable type but this is most likely a string. (required)
The placement
property is where to position the tooltip. Valid options are: top
, right
, bottom
and left
. Defaults to "top"
.
The trigger
property is a string that determines how the tooltip is triggered. Valid options are: click
, hover
, focus
, touch
or just manual
. You may pass multiple triggers; separate them with a space. Pass a string value of "manual" to manually trigger the tooltip. Defaults to "hover focus touch"
.
The className
property is a standard space-separated list of classes to apply to the main tooltip element when it rendered. This can be used to add custom styling to a specific tooltip.
Methods
show
Reveals an element's tooltip.
hide
Hides an element's tooltip.
toggle
Toggles an element's tooltip.
updatePosition
Update element's tooltip relative to the element's position.
destroy
Hides and destroys an element's tooltip.
Examples
var React = require('react');
var ReactDOM = require('react-dom');
var Tipsy = require('react-tipsy');
var MyComponent = React.createClass({
componentDidMount: function() {
this.refs.tooltip.show(); // show the tooltip
this.refs.tooltip.toggle(); // toggle (hide) the tooltip
this.refs.tooltip.show();
this.refs.tooltip.updatePosition(); // update tooltip position
},
render: function() {
return (
<Tipsy ref="tooltip" content="Tooltip on top" trigger="manual">
<button type="button">Tooltip on top></button>
</Tipsy>
);
}
});
react-tipsy
will position the tooltip based on the relative position of the DOM element of the wrapped React Element.
CSS stylesheet
I've built a default stylesheet, dist/react-tipsy.css
, that you may include in your sites/projects.
You can customize the styles by modifying the stylesheet itself or by using less and modifying the less files in the /less
directory.
How does the tooltip get rendered exactly?
react-tipsy
generates a "portal" DOM element in which it renders the actual tooltip content into. Using React's component lifecycle, we can ensure that the tooltip is removed from the DOM as well as the "portal" container.
When a user hovers over the wrapped React element, the tooltip will be displayed. And when the user hovers out, the tooltip will be hidden.
When it comes to users on mobile/tablet devices where mouse events are not present, then you'll have two options to trigger the tooltip: "touch" or "focus". When using "focus" trigger, the tooltip will be visible when the wrapped React element has focus and hidden when blurred. When using "touch" trigger, the tooltip will be visible when the wrapped React element touchstart begins and hidden when touchend event is triggered.