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 | FunctionSee signature. | | | A callback function, called when the tooltip is closing. | | onOpen | FunctionSee signature. | | | A callback function, called when the tooltip is opening. | | isOpen | boolean | | | | | placement | unionPossible 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 | ObjectSee signature. | | | Customize the appearance of certain elements of the tooltip. | | horizontalConstraint | unionPossible 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;
}