@commercetools-uikit/tooltip

Tooltip

Description

Tooltips display informative text when users hover over or focus on an element.

Installation

yarn add @commercetools-uikit/tooltip

npm --save install @commercetools-uikit/tooltip

Additionally install the peer dependencies (if not present)

yarn add react

npm --save install react

Usage

import { forwardRef } from 'react';
import PropTypes from 'prop-types';
import ReactDOM from 'react-dom';
import styled from '@emotion/styled';
import Tooltip from '@commercetools-uikit/tooltip';

/* 1. Standard example */
const ExampleStandard = () => (
  <Tooltip
    placement="left"
    title="If you buy a pizza, you will also get a free ice cream :)"
  >
    <button onClick={() => {}}>Submit</button>
  </Tooltip>
);

/**
 * 2. Working with disabled child elements
 *
 * When you use a tooltip with a disabled element, you should define the
 * style `pointer-events: none` to the disabled element to stop it from capturing events.
 * The Button components from UIKit already support this functionality.
 */
const ExampleWithDisabledElements = () => (
  <Tooltip
    placement="left"
    title="You do not have permission to delete the database"
  >
    <button disabled onClick={() => {}} style={{ pointerEvents: 'none' }}>
      Delete production database
    </button>
  </Tooltip>
);

/**
 * 3. Customizing the wrapper
 *
 * The tooltip applies event listeners (`onMouseOver`, `onMouseLeave`, `onFocus`,
 * and `onBlur`) to a wrapping `div` component around the children element.
 * By default, this wrapper is displayed with style `inline-block`.
 * If you want to customize this behaviour, then you can pass in a custom element.
 * Be sure to use `React.forwardRef`, as we need the to pass the ref to the wrapper.
 */
const Wrapper = forwardRef((props, ref) => (
  <div ref={ref} style={{ display: 'block' }} {...props}>
    {props.children}
  </div>
));
Wrapper.propTypes = {
  children: PropTypes.node.isRequired,
};
const FullWidthButton = styled.button`
  display: block;
  width: 100%;
`;
const ExampleWithCustomWrapper = () => (
  <Tooltip title="Delete" components={{ WrapperComponent: Wrapper }}>
    <FullWidthButton>Submit</FullWidthButton>
  </Tooltip>
);

/**
 * 4. Customizing the tooltip body
 *
 * You can customize the look and feel of the tooltip body by passing in a custom `BodyComponent`.
 */
const Body = styled.div`
  color: red;
`;
const ExampleWithCustomBody = () => (
  <Tooltip title="Delete" components={{ BodyComponent: Body }}>
    <button>Submit</button>
  </Tooltip>
);

/**
 * 5. Customizing where the portal is rendered
 *
 * When you are dealing with virtualized components, it can be useful to render
 * the tooltip into another part of the document.
 * You can define a `TooltipWrapperComponent` to do this.
 */
const Portal = (props) => ReactDOM.createPortal(props.children, document.body);
const ExampleWithCustomPortal = () => (
  <Tooltip title="Delete" components={{ TooltipWrapperComponent: Portal }}>
    <button>Submit</button>
  </Tooltip>
);

/**
 * 6. Conditionally displaying tooltips
 *
 * There may be cases when you only want to enable the display of a tooltip under
 * a certain condition. In these cases, you may want to use the `off` prop.
 * In the following example, the tooltip text only appears on hover when the button is disabled.
 */
const ExampleWithConditionals = (props) => (
  <Tooltip
    off={props.isDisabled}
    title="You do not have permission to perform this action"
  >
    <button disabled={props.isDisabled}>Submit</button>
  </Tooltip>
);
ExampleWithConditionals.propTypes = {
  isDisabled: PropTypes.bool,
};

/**
 * 7. Fine-tuning underlying Popper.js behavior
 *
 * This component uses [Popper.js](https://popper.js.org/) under the hood.
 * Popper provides a way to adjust how tooltip element should behave, by providing
 * a [set of `modifiers`](https://popper.js.org/popper-documentation.html#modifiers).
 * For instance, forcing tooltip to stay in the original placement and not to try
 * flipping when it's getting out of boundaries, can be implemented as following:
 */
const ExampleWithCustomPopperBehavior = (props) => (
  <Tooltip
    placement="left"
    title="I will always be on the left side"
    modifiers={{
      preventOverflow: {
        enabled: false,
      },
      flip: {
        enabled: false,
      },
    }}
  >
    <button disabled={props.isDisabled}>Submit</button>
  </Tooltip>
);
ExampleWithCustomPopperBehavior.propTypes = {
  isDisabled: PropTypes.bool,
};

export {
  ExampleStandard,
  ExampleWithDisabledElements,
  ExampleWithCustomWrapper,
  ExampleWithCustomBody,
  ExampleWithCustomPortal,
  ExampleWithConditionals,
  ExampleWithCustomPopperBehavior,
};

Properties

Props	Type	Required	Default	Description
children	ReactElement	✅
showAfter	number		300	Delay (in milliseconds) between the start of the user interaction, and showing the tooltip.
closeAfter	number		200	Delay (in milliseconds) between the end of the user interaction, and the closing of the tooltip.
styles	Record			Custom css-in-js object styles for the tooltip body.
off	boolean		false	Determines if the tooltip should not appear.
id	string			An identifier for the tooltip, used for aria-describedby.
onClose	Function See signature.			A callback function, called when the tooltip is closing.
onOpen	Function See signature.			A callback function, called when the tooltip is opening.
isOpen	boolean
placement	union Possible values: , 'top', 'top-start', 'top-end', 'right', 'right-start', 'right-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end'		'top'	How the tooltip is positioned relative to the child element.
title	string	✅		The message to show in the tooltip.
modifiers	Modifiers			Provides a way to fine-tune an appearance of underlying Popper tooltip element. For more information, please check Popper.js documentation.
components	Object See signature.			Customize the appearance of certain elements of the tooltip.
horizontalConstraint	union Possible values: , 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 'scale', 'auto'		'scale'	Horizontal size limit of the tooltip.

Signatures

Signature onClose

(e?: ChangeEvent | FocusEvent) => void

Signature onOpen

(e?: ChangeEvent | FocusEvent) => void

Signature components

{
  /**
   * The component rendered as the tooltip body.
   */
  BodyComponent?: ComponentType;
  /**
   * Where the tooltip should be rendered. This can be useful to render the tooltip into another part of the document, using React portal.
   */
  TooltipWrapperComponent?: ComponentType;
  /**
   * A custom component wrapper for the tooltip.
   */
  WrapperComponent?: ComponentType;
}