Tooltip | Mineral UI

Tooltips display supporting information to disambiguate user controls and text.

Examples #

Import Syntax #

import Tooltip from 'mineral-ui/Tooltip';

Basic Usage #

Tooltips wrap the triggering component. Placement is relative to the location of the trigger. Tooltips will change position relative to the trigger automatically depending on viewport constraints.

<Tooltip content="Edit your account settings">
  <Button iconStart={<IconPerson title="account settings"/>} />
</Tooltip>

In Prose #

Tooltips can add information to prose.

Here's some prose with a Tooltip in the middle of it.

<DemoLayout>
  <p>
    Here's some prose with a <Tooltip content="Light years star stuff" isOpen usePortal>Tooltip</Tooltip> in the middle of it.
  </p>
</DemoLayout>

Placement #

The placement prop determines the initial placement of the Tooltip content relative to the trigger. The Tooltip will still react to viewport edges and scrolling.

<DemoLayout>
  <Tooltip
    content="Light years star stuff harvesting star light citizens of distant epochs."
    isOpen
    placement="bottom">
    <Button variant="danger" iconStart={<IconDelete title="delete" />}/>
  </Tooltip>
</DemoLayout>

Overflow #

A Tooltip can extend beyond its bounding container (the blue area in this example) even if the container has an overflow: hidden style. See the portal example for even greater control.

<OverflowContainer>
  <Tooltip
    content="Light years star stuff"
    placement="top"
    isOpen>
    <Button>Button</Button>
  </Tooltip>
</OverflowContainer>

Scrolling Container #

Tooltip will attempt to stay visible in an overflow: scroll container.

<ScrollParent>
  <Tooltip
    content="Light years star stuff"
    placement="left"
    isOpen>
    <Button>Button</Button>
  </Tooltip>
</ScrollParent>

Use a portal to render the Tooltip to the body of the page rather than as a sibling of the trigger. This can be useful to visually "break out" of a container with overflow or z-index styles. Note that you may have to adjust the modifiers to get the exact behavior that you want.

<ScrollParent>
  <Tooltip
    content="Light years star stuff"
    placement="bottom"
    usePortal
    isOpen
    modifiers={{
      preventOverflow: {
        escapeWithReference: true
      }
    }}>
    <Button>Button</Button>
  </Tooltip>
</ScrollParent>

Cursor #

Tooltips can apply any of the valid CSS cursor values.

<DemoLayout>
  <Tooltip cursor="help" content="Help">Help</Tooltip>
  <Tooltip cursor="not-allowed" content="Not Allowed">Not Allowed</Tooltip>
  <Tooltip cursor="move" content="Move">Move</Tooltip>
</DemoLayout>

Disabled #

Disabled Tooltips simply don't display the tooltip content upon interaction. The child is unaffected.

<Tooltip content="Edit your account settings" disabled>
  <Button iconStart={<IconPerson title="account settings"/>} />
</Tooltip>

Controlled #

Tooltip controls its own state by default, and can optionally be managed by the application as a controlled component through the isOpen prop. Callbacks for onOpen and onClose are also provided.

class App extends Component {
  constructor(props) {
    super(props);
    this.state = {isOpen: true};
    this.toggleTooltip = this.toggleTooltip.bind(this);
  }

  toggleTooltip() {
    this.setState(prevState => ({ isOpen: !prevState.isOpen }));
  }

  render() {
    const label = this.state.isOpen ? 'Close Tooltip' : 'Open Tooltip';
    return (
      <DemoLayout>
        <Tooltip
          content="This tooltip is controlled"
          isOpen={this.state.isOpen}
          placement="top">
          <Button>Button</Button>
        </Tooltip>
        <Button onClick={this.toggleTooltip}>{label}</Button>
      </DemoLayout>
    );
  }
}

API & Theme #

Tooltip Props #

The Tooltip component takes the following React props.

Name	Type	Default	Description
children	React$Node	required	Trigger for the Tooltip
content	string	required	Content of the Tooltip
cursor	string		Cursor applied when hovering the tooltip trigger; accepts any valid CSS value
defaultIsOpen	boolean		Open the Tooltip upon initialization. Primarily for use with uncontrolled components.
disabled	boolean		Disables the Tooltip
hasArrow	boolean	true	Include an arrow on the Tooltip content pointing to the trigger
id	string		Id of the Tooltip
isOpen	boolean		Determines whether the Tooltip is open. For use with controlled components.
modifiers	Object		Plugins that are used to alter behavior. See PopperJS docs for options.
onClose			Called when Tooltip is closed
onOpen			Called when Tooltip is opened
placement		'bottom'	Placement of the Tooltip
positionFixed	boolean		Apply fixed positioning to the content
usePortal	boolean		Use a Portal to render the Tooltip to the body rather than as a sibling to the trigger.

Undocumented properties, including as and css, will be applied to the root element.

Tooltip Theme Variables #

These variables can be used as hooks to override this component's style at either a local or global level. The theme referenced below is whatever theme is available from props to the instance of this component.

Variable	Value
TooltipArrow_backgroundColor	theme.panel_backgroundColor_inverted
TooltipArrow_borderColor	theme.panel_borderColor_inverted
TooltipContent_backgroundColor	theme.panel_backgroundColor_inverted
TooltipContent_borderColor	theme.panel_borderColor_inverted
TooltipContent_borderRadius	theme.borderRadius_1
TooltipContent_boxShadow	theme.boxShadow_2
TooltipContent_color	theme.color_inverted
TooltipContent_paddingVertical	theme.space_inset_sm
TooltipContent_maxWidth	18em
TooltipContent_zIndex	theme.zIndex_100
TooltipContentBlock_marginVertical	0
TooltipContentBlock_paddingHorizontal	theme.space_inset_md
TooltipTriggerText_borderStyle	dashed
TooltipTriggerText_borderColor	currentcolor
TooltipTriggerText_borderWidth	1px

Usage #

When/How to Use #

Use Tooltips to provide contextual annotations to user controls. Tooltip content should be concise and helpful. Content should also be static. Users don't expect the contents to change and are unlikely to notice changes since they are hidden.

Tooltips are not predictable interactions for mobile device users and should be avoided.

Use a Popover instead of a Tooltip when users need to interact with the content. For example, walkthroughs and dismissable new feature announcements should be built with Popovers.

Best Practices #

Use Tooltips to provide supplemental information for a user control, such as titles and keyboard shortcuts, when the interface design doesn't allow space for a text label.

Use Tooltips to annotate the controls for rarely used features or features that can be interpreted in several ways. For instance, these buttons are for voting, not scrolling or prioritizing.

Don't use Tooltips to hide important information. Information hidden inside a Tooltip is much less likely to be discovered by the user.

Friedrich Mohs

Born: January 29, 1773
Died: September 29, 1839

Don't place Tooltips such that they prevent the user from reviewing their input.

Name

Don't place useless or redundant content in a Tooltip. Tooltip content should be helpful.

Don't put large strings of text inside a Tooltip's content. Tooltips are intended for short, simple content.

Don't litter your prose with Tooltips. They clutter the text and make it hard to read.

Lorem ipsum dolor sit consectetur adipiscing elit, sed eiusmod tempor incididunt ut et dolore magna aliqua. enim ad minim veniam, nostrud exercitation ullamco laboris ut aliquip ex ea consequat. Duis aute irure in reprehenderit in voluptate esse cillum dolore eu nulla pariatur. Excepteur sint cupidatat non proident, sunt culpa qui officia deserunt anim id est laborum.