Tooltip

A tooltip is a brief, informative message that appears when a user interacts with an element. Tooltips are usually initiated in one of two ways: through a mouse-hover gesture or through a keyboard-hover gesture.

The Tooltip component follows the WAI-ARIA Tooltip Pattern.

Import#

import { Tooltip } from "@chakra-ui/react"

Usage#

If the children of Tooltip is a string, we wrap with in a span with tabIndex set to 0, to ensure it meets the accessibility requirements.

Note 🚨: If the Tooltip is wrapping a functional component, ensure that the functional component accepts a ref using forwardRef.

Hover me

<Tooltip label="Hey, I'm here!" aria-label="A tooltip">
  Hover me
</Tooltip>

<Tooltip label="Hey, I'm here!" aria-label="A tooltip">
  Hover me
</Tooltip>

Editable Example

With an icon#

<Tooltip label="Phone number" fontSize="md">
  <PhoneIcon />
</Tooltip>

<Tooltip label="Phone number" fontSize="md">
  <PhoneIcon />
</Tooltip>

Editable Example

Note 🚨: If you're wrapping an icon from react-icons, you need to also wrap the icon in a span element as react-icons icons do not use forwardRef.

With arrow#

<Tooltip hasArrow label="Search places" bg="gray.300" color="black">
  <SearchIcon />
</Tooltip>

<Tooltip hasArrow label="Search places" bg="gray.300" color="black">
  <SearchIcon />
</Tooltip>

Editable Example

If the children of the tooltip is a focusable element, the tooltip will show when you focus or hover on the element, and will hide when you blur or move cursor out of the element.

<Tooltip hasArrow label="Search places" bg="red.600">
  <Button>Button</Button>
</Tooltip>

<Tooltip hasArrow label="Search places" bg="red.600">
  <Button>Button</Button>
</Tooltip>

Editable Example

<Tooltip isDisabled>
  <SearchIcon />
</Tooltip>

<Tooltip isDisabled>
  <SearchIcon />
</Tooltip>

Editable Example

Placement#

Using the placement prop you can adjust where your tooltip will be displayed.

<VStack spacing={6}>
  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Auto start" placement="auto-start">
      <Button>Auto-Start</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Auto" placement="auto">
      <Button>Auto</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Auto end" placement="auto-end">
      <Button>Auto-End</Button>
    </Tooltip>
  </HStack>

  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Top start" placement="top-start">
      <Button>Top-Start</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Top" placement="top">
      <Button>Top</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Top end" placement="top-end">
      <Button>Top-End</Button>
    </Tooltip>
  </HStack>

  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Right start" placement="right-start">
      <Button>Right-Start</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Right" placement="right">
      <Button>Right</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Right end" placement="right-end">
      <Button>Right-End</Button>
    </Tooltip>
  </HStack>

  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Bottom start" placement="bottom-start">
      <Button>Bottom Start</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Bottom" placement="bottom">
      <Button>Bottom</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Bottom end" placement="bottom-end">
      <Button>Bottom End</Button>
    </Tooltip>
  </HStack>

  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Left start" placement="left-start">
      <Button>Left-Start</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Left" placement="left">
      <Button>Left</Button>
    </Tooltip>

    <Tooltip shouldWrapChildren label="Left end" placement="left-end">
      <Button>Left-End</Button>
    </Tooltip>
  </HStack>
</VStack>

<VStack spacing={6}>
  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Auto start" placement="auto-start">
      <Button>Auto-Start</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Auto" placement="auto">
      <Button>Auto</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Auto end" placement="auto-end">
      <Button>Auto-End</Button>
    </Tooltip>
  </HStack>
  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Top start" placement="top-start">
      <Button>Top-Start</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Top" placement="top">
      <Button>Top</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Top end" placement="top-end">
      <Button>Top-End</Button>
    </Tooltip>
  </HStack>
  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Right start" placement="right-start">
      <Button>Right-Start</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Right" placement="right">
      <Button>Right</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Right end" placement="right-end">
      <Button>Right-End</Button>
    </Tooltip>
  </HStack>
  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Bottom start" placement="bottom-start">
      <Button>Bottom Start</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Bottom" placement="bottom">
      <Button>Bottom</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Bottom end" placement="bottom-end">
      <Button>Bottom End</Button>
    </Tooltip>
  </HStack>
  <HStack spacing={6}>
    <Tooltip shouldWrapChildren label="Left start" placement="left-start">
      <Button>Left-Start</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Left" placement="left">
      <Button>Left</Button>
    </Tooltip>
    <Tooltip shouldWrapChildren label="Left end" placement="left-end">
      <Button>Left-End</Button>
    </Tooltip>
  </HStack>
</VStack>

Editable Example

More examples#

<Wrap spacing={6}>
  <WrapItem>
    <Tooltip shouldWrapChildren label="I close on click">
      <Button>Close on Click - true(default)</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip
      shouldWrapChildren
      label="I don't close on click"
      closeOnClick={false}
    >
      <Button>Close on Click - false</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip shouldWrapChildren label="I am always open" placement="top" isOpen>
      <Button>Always Open</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip
      shouldWrapChildren
      label="I am open by default"
      placement="left"
      defaultIsOpen
    >
      <Button>Open on startup</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip shouldWrapChildren label="Opened after 500ms" openDelay={500}>
      <Button>Delay Open - 500ms</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip shouldWrapChildren label="Closed after 500ms" closeDelay={500}>
      <Button>Delay Close - 500ms</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip
      shouldWrapChildren
      label="I have 15px arrow"
      hasArrow
      arrowSize={15}
    >
      <Button>Arrow size - 15px</Button>
    </Tooltip>
  </WrapItem>
</Wrap>

<Wrap spacing={6}>
  <WrapItem>
    <Tooltip shouldWrapChildren label="I close on click">
      <Button>Close on Click - true(default)</Button>
    </Tooltip>
  </WrapItem>
  <WrapItem>
    <Tooltip
      shouldWrapChildren
      label="I don't close on click"
      closeOnClick={false}
    >
      <Button>Close on Click - false</Button>
    </Tooltip>
  </WrapItem>
  <WrapItem>
    <Tooltip shouldWrapChildren label="I am always open" placement="top" isOpen>
      <Button>Always Open</Button>
    </Tooltip>
  </WrapItem>
  <WrapItem>
    <Tooltip
      shouldWrapChildren
      label="I am open by default"
      placement="left"
      defaultIsOpen
    >
      <Button>Open on startup</Button>
    </Tooltip>
  </WrapItem>
  <WrapItem>
    <Tooltip shouldWrapChildren label="Opened after 500ms" openDelay={500}>
      <Button>Delay Open - 500ms</Button>
    </Tooltip>
  </WrapItem>
  <WrapItem>
    <Tooltip shouldWrapChildren label="Closed after 500ms" closeDelay={500}>
      <Button>Delay Close - 500ms</Button>
    </Tooltip>
  </WrapItem>
  <WrapItem>
    <Tooltip
      shouldWrapChildren
      label="I have 15px arrow"
      hasArrow
      arrowSize={15}
    >
      <Button>Arrow size - 15px</Button>
    </Tooltip>
  </WrapItem>
</Wrap>

Editable Example

Props#

Name	Type	Description	Default
children	`ReactNode`	The react component to use as the trigger for the tooltip	-
aria-label	`string`	The accessible, human friendly label to use for screen readers. If passed, tooltip will show the content `label` but expose only `aria-label` to assistive technologies	-
arrowPadding	`number`	The distance of the arrow to its next border (numeric) E.g. arrowPadding = borderRadius * 2	-
arrowShadowColor	`string`		-
arrowSize	`number`		-
closeDelay	`number`	Delay (in ms) before hiding the tooltip	`0ms`
closeOnClick	`boolean`	If `true`, the tooltip will hide on click	-
closeOnMouseDown	`boolean`	If `true`, the tooltip will hide while the mouse is down	-
colorScheme	`string`		-
defaultIsOpen	`boolean`	If `true`, the tooltip will be initially shown	-
gutter	`number`		-
hasArrow	`boolean`	If `true`, the tooltip will show an arrow tip	-
isDisabled	`boolean`		-
isOpen	`boolean`	If `true`, the tooltip will be shown (in controlled mode)	-
label	`ReactNode`	The label of the tooltip	-
modifiers	`Modifier<string, any>[]`		-
offset	`[number, number]`		-
onClose	`(() => void)`	Callback to run when the tooltip hides	-
onOpen	`(() => void)`	Callback to run when the tooltip shows	-
openDelay	`number`	Delay (in ms) before showing the tooltip	`0ms`
placement	`"top" \| "right" \| "bottom" \| "left" \| "auto" \| "auto-start" \| "auto-end" \| "top-start" \| "top-end" \| "bottom-start" \| "bottom-end" \| "right-start" \| "right-end" \| "left-start" \| "left-end"`	The Popper.js placement of the tooltip	-
shouldWrapChildren	`boolean`	If `true`, the tooltip will wrap its children in a `<span/>` with `tabIndex=0`	-
size	`string`		-
variant	`string`		-

Edit this page

Tooltip

Import#

Usage#

With an icon#

With arrow#

Tooltip with focusable content#

Disabled Tooltip#

Placement#

More examples#

Props#