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.

Chakra UI Pro: Start your application or marketing site with a growing collection of beautiful and responsive UI components.

Ads via Chakra UI

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 label="Auto start" placement="auto-start">
      <Button>Auto-Start</Button>
    </Tooltip>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Editable Example

More examples#

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

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

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

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

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

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

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

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

Editable Example

Props#

`childrenrequired`

Description

The react component to use as the trigger for the tooltip

Type

ReactNode

`aria-label`

Description

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

Type

string

`arrowPadding`

Description

The padding required to prevent the arrow from reaching the very edge of the popper.

Type

number

Default

8

`arrowShadowColor`

Type

string

`arrowSize`

Type

number

`closeDelay`

Description

Delay (in ms) before hiding the tooltip

Type

number

Default

0ms

`closeOnClick`

Description

If true, the tooltip will hide on click

Type

boolean

`closeOnMouseDown`

Description

If true, the tooltip will hide while the mouse is down

Type

boolean

`colorScheme`

Description

Color Schemes for Tooltip are not implemented in the default theme. You can extend the theme to implement them.

Type

"whiteAlpha" | "blackAlpha" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "cyan" | "purple" | "pink" | "linkedin" | "facebook" | "messenger" | "whatsapp" | "twitter" | "telegram"

`defaultIsOpen`

Description

If true, the tooltip will be initially shown

Type

boolean

`gutter`

Description

The distance or margin between the reference and popper. It is used internally to create an offset modifier. NB: If you define offset prop, it'll override the gutter.

Type

number

Default

8

`hasArrow`

Description

If true, the tooltip will show an arrow tip

Type

boolean

`isDisabled`

Type

boolean

`isOpen`

Description

If true, the tooltip will be shown (in controlled mode)

Type

boolean

`label`

Description

The label of the tooltip

Type

ReactNode

`modifiers`

Description

Array of popper.js modifiers. Check the docs to see the list of possible modifiers you can pass. @see Docs https://popper.js.org/docs/v2/modifiers/

Type

Partial<Modifier<string, any>>[]

`offset`

Description

The main and cross-axis offset to displace popper element from its reference element.

Type

[crossAxis: number, mainAxis: number]

`onClose`

Description

Callback to run when the tooltip hides

Type

(() => void)

`onOpen`

Description

Callback to run when the tooltip shows

Type

(() => void)

`openDelay`

Description

Delay (in ms) before showing the tooltip

Type

number

Default

0ms

`placement`

Description

The Popper.js placement of the tooltip

Type

"bottom" | "left" | "right" | "top" | "auto" | "auto-start" | "auto-end" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end"

`portalProps`

Description

Props to be forwarded to the portal component

Type

Pick<PortalProps, "appendToParentPortal" | "containerRef">

`shouldWrapChildren`

Description

If true, the tooltip will wrap its children in a `<span/>` with `tabIndex=0`

Type

boolean

`size`

Description

Sizes for Tooltip are not implemented in the default theme. You can extend the theme to implement them.

Type

string

`variant`

Description

Variants for Tooltip are not implemented in the default theme. You can extend the theme to implement them.

Type

string

Edit this page

Tooltip

Import#

Usage#

With an icon#

With arrow#

Tooltip with focusable content#

Disabled Tooltip#

Placement#

More examples#

Props#

`childrenrequired`

`aria-label`

`arrowPadding`

`arrowShadowColor`

`arrowSize`

`closeDelay`

`closeOnClick`

`closeOnMouseDown`

`colorScheme`

`defaultIsOpen`

`gutter`

`hasArrow`

`isDisabled`

`isOpen`

`label`

`modifiers`

`offset`

`onClose`

`onOpen`

`openDelay`

`placement`

`portalProps`

`shouldWrapChildren`

`size`

`variant`