gem-hunter
Language: TypeScript
A React hook to effortlessly build smart tooltips.
A React hook to effortlessly build smart tooltips. Based on react-popper and popper.js.
- This is the documentation for 4.x which introduced the
usePopperTooltiphook.- If you're looking for the render prop version, see 3.x docs.
- If you're looking to upgrade from 3.x render prop to 4.x hook, please refer to our migration guide.
You can install react-popper-tooltip with npm or yarn.
npm i react-popper-tooltip
# or
yarn add react-popper-tooltipThis example illustrates how to create a minimal tooltip with default settings and using our default CSS file.
import * as React from 'react'; import { usePopperTooltip } from 'react-popper-tooltip'; import 'react-popper-tooltip/dist/styles.css'; function App() { const { getArrowProps, getTooltipProps, setTooltipRef, setTriggerRef, visible, } = usePopperTooltip(); return ( <div className="App"> <button type="button" ref={setTriggerRef}> Trigger </button> {visible && ( <div ref={setTooltipRef} {...getTooltipProps({ className: 'tooltip-container' })} > <div {...getArrowProps({ className: 'tooltip-arrow' })} /> Tooltip </div> )} </div> ); } render(<App />, document.getElementById('root'));
With react-popper-tooltip, you can use CSS, LESS, SASS, or any CSS-in-JS library you're already using in your project. However, we do provide a minimal CSS-file file you can use for a quick start or as a reference to create your own tooltip styles.
Import react-popper-tooltip/dist/styles.css to import it into your project. Add classes
tooltip-container and tooltip-arrow to the tooltip container and arrow element accordingly.
While the tooltip is being displayed, you have access to some attributes on the tooltip container. You can use them in your CSS in specific scenarios.
data-popper-placement: contains the current tooltip placement. You can use it to properly offset and display the
arrow element (e.g., if the tooltip is displayed on the right, the arrow should point to the left and vice versa).
data-popper-reference-hidden: set to true when the trigger element is fully clipped and hidden from view, which
causes the tooltip to appear to be attached to nothing. Set to false otherwise.
data-popper-escaped: set to true when the tooltip escapes the trigger element's boundary (and so it appears
detached). Set to false otherwise.
data-popper-interactive: contains the current interactive option value.
const { getArrowProps, getTooltipProps, setTooltipRef, setTriggerRef, tooltipRef, triggerRef, visible, ...popperProps } = usePopperTooltip( { closeOnOutsideClick, closeOnTriggerHidden, defaultVisible, delayHide, delayShow, followCursor, interactive, mutationObserverOptions, offset, onVisibleChange, placement, trigger, visible, }, popperOptions );
closeOnOutsideClick: boolean, defaults to trueIf true, closes the tooltip when user clicks outside the trigger element.
closeOnTriggerHidden: boolean, defaults to falseWhether to close the tooltip when its trigger is out of boundary.
delayHide: number, defaults to 0Delay in hiding the tooltip (ms).
delayShow: number, defaults to 0Delay in showing the tooltip (ms).
defaultVisible: boolean, defaults to falseThe initial visibility state of the tooltip when the hook is initialized.
followCursor: boolean, defaults to falseIf true, the tooltip will stick to the cursor position. You would probably want to use this option with hover trigger.
mutationObserverOptions: MutationObserverInit | null, defaults
to { attributes: true, childList: true, subtree: true }Options to MutationObserver , used internally for updating tooltip position based on its DOM changes. When the tooltip is visible and its content changes, it automatically repositions itself. In some cases you may need to change which parameters to observe or opt-out of tracking the changes at all.
offset: [number, number], defaults to [0, 6]This is a shorthand for popperOptions.modifiers offset modifier option. The default value means the tooltip will be
placed 6px away from the trigger element (to reserve enough space for the arrow element).
We use this default value to match the size of the arrow element from our default CSS file. Feel free to change it if you are using your own styles.
See offset modifier docs.
popperOptions takes precedence over this option.
onVisibleChange: (state: boolean) => voidCalled with the tooltip state, when the visibility of the tooltip changes.
trigger: TriggerType | TriggerType[] | null, where TriggerType = 'click' | 'right-click' | 'hover' | 'focus',
defaults to hoverEvent or events that trigger the tooltip. Use null if you want to disable all events. It's useful in cases when
you control the state of the tooltip.
visible: booleanThe visibility state of the tooltip. Use this prop if you want to control the state of the tooltip. Note that delayShow and delayHide are not used if the tooltip is controlled. You have to apply delay on your external state.
react-popper-tooltip manages its own state internally and calls onVisibleChange handler with any relevant changes.
However, if more control is needed, you can pass this prop, and the state becomes controlled. As soon as it's not undefined, internally, react-popper-tooltip will determine its state based on your prop's value rather than its own internal state.
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';The preferred placement of the tooltip. This is an alias for popperOptions.placement option.
popperOptions takes precedence over this option.
interactive: boolean, defaults to falseIf true, hovering the tooltip will keep it open. Normally, if you trigger the tooltip on hover event, the tooltip
closes when the mouse cursor moves out of the trigger element. If it moves to the tooltip element, the tooltip stays
open. It's useful if you want to allow your users to interact with the tooltip's content (select and copy text, click a
link, etc.). In this case you might want to increase delayHide value to give the user more time to react.
popperOptions: { placement, modifiers, strategy, onFirstUpdate }These options passed directly to the underlying usePopper hook.
See https://popper.js.org/docs/v2/constructors/#options.
Keep in mind, if you set placement or any modifiers here, it replaces offset and placement options above. They
won't be merged into the final object. You have to add offset modifier along with others here to make it work.
triggerRef: HTMLElement | nullThe trigger DOM element ref.
tooltipRef: HTMLElement | nullThe tooltip DOM element ref.
setTooltipRef: (HTMLElement | null) => void | nullA tooltip callback ref. Must be assigned to the tooltip's ref prop.
setTriggerRef: (HTMLElement | null) => void | nullA trigger callback ref. Must be assigned to the trigger's ref prop.
visible: booleanThe current visibility state of the tooltip. Use it to display or hide the tooltip.
getArrowProps: (props) => mergedPropsThis function merges your props and the internal props of the arrow element. We recommend passing all your props to that function rather than applying them on the element directly to avoid your props being overridden or overriding the internal props.
It returns the merged props that you need to pass to the arrow element.
getTooltipProps: (props) => mergedPropsThis function merges your props and the internal props of the tooltip element. We recommend passing all your props to that function rather than applying them on the element directly to avoid your props being overridden or overriding the internal props.
It returns the merged props that you need to pass to tooltip element.
popperProps: { update, forceUpdate, state }Some props returned by the underlying usePopper hook.
See https://popper.js.org/react-popper/v2/hook.
This doesn't include styles and attributes props. They are included into getArrowProps and getTooltipProps prop
getters.