| 1 | # react-tooltip
|
| 2 |
|
| 3 | [](https://www.npmjs.org/package/react-tooltip)
|
| 4 | [](https://github.com/prettier/prettier)
|
| 5 | [![npm download][download-image]][download-url]
|
| 6 | [](https://travis-ci.org/wwayne/react-tooltip)
|
| 7 | [](https://github.com/semantic-release/semantic-release)
|
| 8 |
|
| 9 | [download-image]: https://img.shields.io/npm/dm/react-tooltip.svg?style=flat-square
|
| 10 | [download-url]: https://npmjs.org/package/react-tooltip
|
| 11 |
|
| 12 | ## Demo
|
| 13 |
|
| 14 | [](https://codesandbox.io/s/heuristic-curran-bddeu?fontsize=14&hidenavigation=1&theme=dark)
|
| 15 |
|
| 16 | Or see it on [Github Page](https://wwayne.github.io/react-tooltip).
|
| 17 |
|
| 18 | ## Maintainers
|
| 19 |
|
| 20 | [aronhelser](https://github.com/aronhelser) Passive maintainer - accepting PRs and doing minor testing, but not fixing issues or doing active development.
|
| 21 |
|
| 22 | [roggervalf](https://github.com/roggervalf) Active maintainer - accepting PRs and doing minor testing, fixing issues or doing active development.
|
| 23 |
|
| 24 | [huumanoid](https://github.com/huumanoid) (inactive)
|
| 25 |
|
| 26 | We would gladly accept a new maintainer to help out!
|
| 27 |
|
| 28 | ## Installation
|
| 29 |
|
| 30 | ```sh
|
| 31 | npm install react-tooltip
|
| 32 | ```
|
| 33 |
|
| 34 | or
|
| 35 |
|
| 36 | ```sh
|
| 37 | yarn add react-tooltip
|
| 38 | ```
|
| 39 |
|
| 40 | ## Usage
|
| 41 |
|
| 42 | ### Using NPM
|
| 43 |
|
| 44 | 1 . Require react-tooltip after installation
|
| 45 |
|
| 46 | ```js
|
| 47 | import ReactTooltip from 'react-tooltip';
|
| 48 | ```
|
| 49 |
|
| 50 | 2 . Add data-tip = "your placeholder" to your element
|
| 51 |
|
| 52 | ```jsx
|
| 53 | <p data-tip="hello world">Tooltip</p>
|
| 54 | ```
|
| 55 |
|
| 56 | 3 . Include react-tooltip component
|
| 57 |
|
| 58 | ```jsx
|
| 59 | <ReactTooltip />
|
| 60 | ```
|
| 61 |
|
| 62 | ### Standalone
|
| 63 |
|
| 64 | You can import `node_modules/react-tooltip/dist/index.js` into your page. Please make sure that you have already imported `react` and `react-dom` into your page.
|
| 65 |
|
| 66 | ## Options
|
| 67 |
|
| 68 | Notes:
|
| 69 |
|
| 70 | - The tooltip sets `type: dark` `place: top` `effect: float` as **default** attributes. You don't have to add these options if you don't want to change the defaults
|
| 71 | - The option you set on `<ReactTooltip />` component will be implemented on every tooltip in a same page: `<ReactTooltip effect="solid" />`
|
| 72 | - The option you set on a specific element, for example: `<a data-type="warning"></a>` will only affect this specific tooltip
|
| 73 |
|
| 74 | | Global | Specific | Type | Values | Description |
|
| 75 | | :--------------- | :-------------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 76 | | place | data-place | String | top, right, bottom, left | placement |
|
| 77 | | type | data-type | String | dark, success, warning, error, info, light | theme |
|
| 78 | | effect | data-effect | String | float, solid | behaviour of tooltip |
|
| 79 | | event | data-event | String | e.g. click | custom event to trigger tooltip |
|
| 80 | | eventOff | data-event-off | String | e.g. click | custom event to hide tooltip (only makes effect after setting event attribute) |
|
| 81 | | globalEventOff | | String | e.g. click | global event to hide tooltip (global only) |
|
| 82 | | isCapture | data-iscapture | Bool | true, false | when set to true, custom event's propagation mode will be capture |
|
| 83 | | offset | data-offset | Object | top, right, bottom, left | `data-offset="{'top': 10, 'left': 10}"` for specific and `offset={{top: 10, left: 10}}` for global |
|
| 84 | | multiline | data-multiline | Bool | true, false | support `<br>`, `<br />` to make multiline |
|
| 85 | | className | data-class | String | | extra custom class, can use !important to overwrite react-tooltip's default class |
|
| 86 | | html | data-html | Bool | true, false | `<p data-tip="<p>HTML tooltip</p>" data-html={true}></p>` or `<ReactTooltip html={true} />`, but see [Security Note](#security-note) below. |
|
| 87 | | delayHide | data-delay-hide | Number | | `<p data-tip="tooltip" data-delay-hide='1000'></p>` or `<ReactTooltip delayHide={1000} />` |
|
| 88 | | delayShow | data-delay-show | Number | | `<p data-tip="tooltip" data-delay-show='1000'></p>` or `<ReactTooltip delayShow={1000} />` |
|
| 89 | | delayUpdate | data-delay-update | Number | | `<p data-tip="tooltip" data-delay-update='1000'></p>` or `<ReactTooltip delayUpdate={1000} />` Sets a delay in calling getContent if the tooltip is already shown and you mouse over another target |
|
| 90 | | insecure | null | Bool | true, false | Whether to inject the style header into the page dynamically (violates CSP style-src but is a convenient default) |
|
| 91 | | border | data-border | Bool | true, false | Add one pixel white border |
|
| 92 | | textColor | data-text-color | String | e.g. red | Popup text color |
|
| 93 | | backgroundColor | data-background-color | String | e.g. yellow | Popup background color |
|
| 94 | | borderColor | data-border-color | String | e.g. green | Popup border color - enabled by the `border` value |
|
| 95 | | arrowColor | data-arrow-color | String | e.g. #fff | Popup arrow color - if not specified, will use the `backgroundColor` value |
|
| 96 | | getContent | null | Func or Array | (dataTip) => {}, [(dataTip) => {}, Interval] | Generate the tip content dynamically |
|
| 97 | | afterShow | null | Func | (evt) => {} | Function that will be called after tooltip show, with event that triggered show |
|
| 98 | | afterHide | null | Func | (evt) => {} | Function that will be called after tooltip hide, with event that triggered hide |
|
| 99 | | overridePosition | null | Func | ({left:number, top: number}, currentEvent, currentTarget, node, place, desiredPlace, effect, offset) => ({left: number, top: number}) | Function that will replace tooltip position with custom one |
|
| 100 | | disable | data-tip-disable | Bool | true, false | Disable the tooltip behaviour, default is false |
|
| 101 | | scrollHide | data-scroll-hide | Bool | true, false | Hide the tooltip when scrolling, default is true |
|
| 102 | | resizeHide | null | Bool | true, false | Hide the tooltip when resizing the window, default is true |
|
| 103 | | wrapper | null | String | div, span | Selecting the wrapper element of the react tooltip, default is div |
|
| 104 | | clickable | null | Bool | true, false | Enables tooltip to respond to mouse (or touch) events, default is false |
|
| 105 |
|
| 106 | ### Security Note
|
| 107 |
|
| 108 | The `html` option allows a tooltip to directly display raw HTML. This is a security risk if any of that content is supplied by the user. Any user-supplied content must be sanitized, using a package like [sanitize-html](https://www.npmjs.com/package/sanitize-html). We chose not to include sanitization after discovering it [increased our package size](https://github.com/wwayne/react-tooltip/issues/429) too much - we don't want to penalize people who don't use the `html` option.
|
| 109 |
|
| 110 | #### Note
|
| 111 |
|
| 112 | 1. **data-tip** is necessary, because `<ReactTooltip />` finds the tooltip via this attribute
|
| 113 | 2. **data-for** corresponds to the **id** of `<ReactTooltip />`
|
| 114 | 3. When using react component as tooltip, you can have many `<ReactTooltip />` in a page but they should have different **id**s
|
| 115 |
|
| 116 | ## Static Methods
|
| 117 |
|
| 118 | ### ReactTooltip.hide(target)
|
| 119 |
|
| 120 | > Hide the tooltip manually, the target is optional, if no target passed in, all existing tooltips will be hidden
|
| 121 |
|
| 122 | ```jsx
|
| 123 | import ReactTooltip from 'react-tooltip'
|
| 124 |
|
| 125 | <p ref={ref => this.fooRef = ref} data-tip='tooltip'></p>
|
| 126 | <button onClick={() => { ReactTooltip.hide(this.fooRef) }}></button>
|
| 127 | <ReactTooltip />
|
| 128 | ```
|
| 129 |
|
| 130 | ### ReactTooltip.rebuild()
|
| 131 |
|
| 132 | > Rebinding all tooltips
|
| 133 |
|
| 134 | ### ReactTooltip.show(target)
|
| 135 |
|
| 136 | > Show specific tooltip manually, for example:
|
| 137 |
|
| 138 | ```jsx
|
| 139 | import ReactTooltip from 'react-tooltip'
|
| 140 |
|
| 141 | <p ref={ref => this.fooRef = ref} data-tip='tooltip'></p>
|
| 142 | <button onClick={() => { ReactTooltip.show(this.fooRef) }}></button>
|
| 143 | <ReactTooltip />
|
| 144 | ```
|
| 145 |
|
| 146 | ## Troubleshooting
|
| 147 |
|
| 148 | ### 1. Using tooltip within the modal (e.g. [react-modal](https://github.com/reactjs/react-modal))
|
| 149 |
|
| 150 | The component was designed to set `<ReactTooltip />` once and then use tooltip everywhere, but a lot of people get stuck when using this component in a modal. You can read the discussion [here](https://github.com/wwayne/react-tooltip/issues/130). To solve this problem:
|
| 151 |
|
| 152 | 1. Place `<ReactTooltip />` outside of the `<Modal>`
|
| 153 | 2. Use `ReactTooltip.rebuild()` when opening the modal
|
| 154 | 3. If your modal's z-index happens to be higher than the tooltip's, use the attribute `className` to custom your tooltip's z-index
|
| 155 |
|
| 156 | > I suggest always putting `<ReactTooltip />` in the Highest level or smart component of Redux, so you might need these static
|
| 157 | > method to control tooltip's behaviour in some situations
|
| 158 |
|
| 159 | ### 2. Hide tooltip when getContent returns undefined
|
| 160 |
|
| 161 | When you set `getContent={() => { return }}` you will find the tooltip will display `true`. That's because React will set the value of data-\* to be 'true' automatically if there is no value to be set. So you have to set `data-tip=''` in this situation.
|
| 162 |
|
| 163 | ```jsx
|
| 164 | <p data-tip='' data-for='test'></p>
|
| 165 | <ReactTooltip id='test' getContent={() => { return null }}/>
|
| 166 | ```
|
| 167 |
|
| 168 | Same for empty children, if you don't want show the tooltip when the children is empty
|
| 169 |
|
| 170 | ```jsx
|
| 171 | <p data-tip='' data-for='test'></p>
|
| 172 | <ReactTooltip id='test'>{}</ReactTooltip>
|
| 173 | ```
|
| 174 |
|
| 175 | ### 3. Tooltip not binding to dynamic content
|
| 176 |
|
| 177 | When you render `<ReactTooltip>` ahead of dynamic content, and are using `data-for={id}` attributes
|
| 178 | on new dynamic content, the tooltip will not register its event listener.
|
| 179 |
|
| 180 | For example, you render a generic tooltip in the root of your app, then load a list of content async.
|
| 181 | Elements in the list use the `data-for={id}` attribute to bind the tooltip on hover.
|
| 182 | Since the tooltip has already scanned for data-tip these new elements will not trigger.
|
| 183 |
|
| 184 | One workaround for this is to trigger `ReactTooltip.rebuild()` after the data load to scan for the attribute again,
|
| 185 | to allow event wireup.
|
| 186 |
|
| 187 | #### Example
|
| 188 |
|
| 189 | ```jsx
|
| 190 | <app>
|
| 191 | <ReactTooltip id="foo" />
|
| 192 | <list/>
|
| 193 | </app>
|
| 194 | ```
|
| 195 |
|
| 196 | ```jsx
|
| 197 |
|
| 198 | const dynamicList = (props) => {
|
| 199 |
|
| 200 | useEffect(() => {
|
| 201 | ReactTooltip.rebuild();
|
| 202 | });
|
| 203 |
|
| 204 | return(
|
| 205 | <list>
|
| 206 | {data.map((item)=> {
|
| 207 | <span data-for="foo">My late bound tooltip triggered data</span>
|
| 208 | });}
|
| 209 | </list>
|
| 210 | );
|
| 211 | };
|
| 212 |
|
| 213 | ```
|
| 214 |
|
| 215 | ## Article
|
| 216 |
|
| 217 | [How I insert sass into react component](https://medium.com/@wwayne_me/how-i-insert-sass-into-my-npm-react-component-b46b9811c226#.gi4hxu44a)
|
| 218 |
|
| 219 | ## Contributing
|
| 220 |
|
| 221 | We welcome your contribution! Fork the repo, make some changes, submit a pull-request! Our [contributing](contributing.md) doc has some details.
|
| 222 |
|
| 223 | ## License
|
| 224 |
|
| 225 | MIT
|