Skip to main content

Tooltip

A tooltip is a brief, informative message that appears when a user interacts with an element.

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.

Using custom components​

const CustomCard = React.forwardRef(({ children, ...rest }, ref) => (
  <Box p="1">
    <Tag ref={ref} {...rest}>
      {children}
    </Tag>
  </Box>
));

const CustomToolTip = () => (
  <Tooltip label="Hover me">
    <CustomCard>Tag Here</CustomCard>
  </Tooltip>
);

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

With an icon​

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

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 with focusable content​

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>

Disabling Tooltip​

To disable showing a tooltip, pass the isDisabled prop to the Tooltip component.

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

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>

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>

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
Default
10

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
Default
true

closeOnEsc

Description

If true, the tooltip will hide on pressing Esc key

Type
boolean
Default
true

closeOnMouseDown

Description

If true, the tooltip will hide while the mouse is down @deprecated - use closeOnPointerDown instead

Type
boolean

closeOnPointerDown

Description

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

Type
boolean

closeOnScroll

Type
boolean

colorScheme

Description

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

Type
string

defaultIsOpen

Description

If true, the tooltip will be initially shown

Type
boolean

direction

Description

Theme direction ltr or rtl. Popper's placement will be set accordingly

Type
"ltr" | "rtl"
Default
"ltr"

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>>[]

motionProps

Type
HTMLMotionProps<"div">

offset

Description

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

Type
[number, 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 placement of the popper relative to its reference.

Type
PlacementWithLogical
Default
"bottom"

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
Last updated on by Andrej

On this page