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>

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>

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#

`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

Type

boolean

`closeOnPointerDown`

Description

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

Type

boolean

Default

true

`closeOnScroll`

Type

boolean

Default

false

`defaultIsOpen`

Description

If true, the tooltip will be initially shown

Type

boolean

Default

false

`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

Default

false

`isDisabled`

Type

boolean

Default

false

`isOpen`

Description

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

Type

boolean

Default

false

`label`

Description

The label of the tooltip

Type

type ONLY_FOR_FORMAT =
  | string
  | number
  | boolean
  | ReactElement<any, string | JSXElementConstructor<any>>
  | ReactFragment
  | ReactPortal

`modifiers`

Description

Array of popper.js modifiers. Check the docs to see the list of possible modifiers you can pass.

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

Default

false

The Tooltip component is a single part component. All of the styling is applied directly to the div element.

To learn more about styling single part components, visit the Component Style page.

Theming properties#

The properties that affect the theming of the Tooltip component are:

variant: The visual variant of the button. Variants for this component are not implemented in the default theme.
colorScheme: The color scheme of the button. Color schemes for this component are not implemented in the default theme.
size: The size of the button. Sizes for this component are not implemented in the default theme.

Theming utilities#

defineStyle: a function used to create style objects.
defineStyleConfig: a function used to define the style configuration for a single part component.

import { defineStyle, defineStyleConfig } from '@chakra-ui/react'

Customizing the default theme#

import { defineStyle, defineStyleConfig } from '@chakra-ui/react'

// define the base component styles
const baseStyle = {
  borderRadius: 'md', // add a border radius
  fontWeight: 'normal', // change the font weight
  border: '1px solid', // add a border
}

// export the component theme
export const tooltipTheme = defineStyleConfig({ baseStyle })

After customizing the default theme, we can import it in our theme file and add it in the components property.

import { extendTheme } from '@chakra-ui/react'
import { tooltipTheme } from './components/Tooltip'

const theme = extendTheme({
  components: {
    Tooltip: tooltipTheme,
  },
})

export default theme

This is a crucial step to make sure that any changes that we make to the tooltip theme are applied.

Adding a custom size#

Let's assume we want to create a small, medium, and large size. Here's how we can do that:

import { defineStyle, defineStyleConfig } from '@chakra-ui/react'

// define custom sizes
const sizes = {
  sm: defineStyle({
    fontSize: 'sm',
    py: '1',
    px: '2',
    maxW: '200px',
  }),
  md: defineStyle({
    fontSize: 'md',
    py: '2',
    px: '3',
    maxW: '300px',
  }),
  lg: defineStyle({
    fontSize: 'lg',
    py: '2',
    px: '4',
    maxW: '350px',
  }),
}

// export the component theme
export const tooltipTheme = defineStyleConfig({ sizes })

Every time you're adding anything new to the theme, you need to run the CLI command to get proper autocomplete in your IDE. You can learn more about the CLI tool here.

Adding a custom variant#

Let's assume we want to include a variant that can use a color scheme. Here's how we can do that:

import { defineStyle, defineStyleConfig } from '@chakra-ui/react'

// define styles for custom variant
const colorfulVariant = defineStyle((props) => {
  const { colorScheme: c } = props // add color scheme as a prop
  return {
    _light: {
      bg: `${c}.300`,
      borderColor: `${c}.600`,
      color: `${c}.800`,
    },
    _dark: {
      bg: `${c}.600`,
      borderColor: `${c}.300`,
      color: `${c}.200`,
    },
  }
})

// define custom variants
const variants = {
  colorful: colorfulVariant,
}

// export the component theme
export const tooltipTheme = defineStyleConfig({ variants })

Using a custom color scheme#

Let's assume we want to use our own custom color scale based on our brand. First, we need to define the color scale in the main theme file:

import { extendTheme } from '@chakra-ui/react';
import { tooltipTheme } from './components/Tooltip';

const theme = extendTheme({
  // add a custom color scheme
  colors: {
    brand: {
      50: '#ffeae1',
      ...
      500: '#d24314',
      ...
      900: '#1e0400',
    },
  },

});

export default theme;

Then, we can use the custom color scale as the color scheme for the tooltip:

<Tooltip colorScheme='brand'>...</Tooltip>

Changing the default properties#

Let's assume we want to add a default size, variant, and color scheme of every tooltip in our app. Here's how we can do that:

import { defineStyle, defineStyleConfig } from '@chakra-ui/react'

// define which sizes, variants, and color schemes are applied by default
const defaultProps = {
  size: 'md',
  variant: 'colorful',
  colorScheme: 'brand',
}

// export the component theme
export const tooltipTheme = defineStyleConfig({ defaultProps })

Showcase#

import React from 'react';
import {
  ChakraProvider,
  Box,
  Center,
  SimpleGrid,
  GridItem,
  Text,
  Icon,
  Tooltip,
} from '@chakra-ui/react';
import theme from './theme';
import { ColorModeSwitcher } from './ColorModeSwitcher';
import { QuestionIcon } from '@chakra-ui/icons';

export default function App() {
  return (
    <ChakraProvider theme={theme}>
      <Box position="relative" h="100vh" p={12}>
        <Center>
          <SimpleGrid columns={[1, 1, 1, 2, 3]} spacing="12">
            <GridItem
            border="1px solid"
            borderRadius="xl"
            p={8}
            _light={{ bg: 'gray.200' }}
            _dark={{ bg: 'gray.700' }}
            >
              <Text display="inline-flex" alignItems="baseline">
                Hover the icon for more information.
                <Tooltip
                label="Tooltip with new theme defaults of brand color scheme and medium size."
                placement="top"
                >
                <Icon as={QuestionIcon} mx={2} color="brand.400" />
                </Tooltip>
              </Text>
            </GridItem>
            <GridItem
            border="1px solid"
            borderRadius="xl"
            p={8}
            _light={{ bg: 'gray.200' }}
            _dark={{ bg: 'gray.700' }}
            >
              <Text display="inline-flex" alignItems="baseline">
                Hover the icon for more information.
                <Tooltip
                label="Tooltip with blue color scheme and new large size."
                placement="top"
                colorScheme="blue"
                size="lg"
                >
                <Icon as={QuestionIcon} mx={2} color="blue.400" />
                </Tooltip>
              </Text>
            </GridItem>
            <GridItem
            border="1px solid"
            borderRadius="xl"
            p={8}
            _light={{ bg: 'gray.200' }}
            _dark={{ bg: 'gray.700' }}
            >
              <Text display="inline-flex" alignItems="baseline">
                Hover the icon for more information.
                <Tooltip
                label="Tooltip with green color scheme and new small size."
                placement="top"
                colorScheme="green"
                size="sm"
                >
                <Icon as={QuestionIcon} mx={2} color="green.400" />
                </Tooltip>
              </Text>
            </GridItem>
          </SimpleGrid>
        </Center>
        <ColorModeSwitcher />
      </Box>
    </ChakraProvider>
  );
}

Edit this page on GitHub

Tooltip

Usage#

Using custom components#

With an icon#

With arrow#

Tooltip with focusable content#

Disabling Tooltip#

Placement#

More examples#

Props#

arrowPadding

arrowShadowColor

arrowSize

closeDelay

closeOnClick

closeOnEsc

closeOnMouseDown

closeOnPointerDown

closeOnScroll

defaultIsOpen

direction

gutter

hasArrow

isDisabled

isOpen

label

modifiers

motionProps

offset

onClose

onOpen

openDelay

placement

portalProps

shouldWrapChildren

Theming properties#

Theming utilities#

Customizing the default theme#

Adding a custom size#

Adding a custom variant#

Using a custom color scheme#

Changing the default properties#

Showcase#

`arrowPadding`

`arrowShadowColor`

`arrowSize`

`closeDelay`

`closeOnClick`

`closeOnEsc`

`closeOnMouseDown`

`closeOnPointerDown`

`closeOnScroll`

`defaultIsOpen`

`direction`

`gutter`

`hasArrow`

`isDisabled`

`isOpen`

`label`

`modifiers`

`motionProps`

`offset`

`onClose`

`onOpen`

`openDelay`

`placement`

`portalProps`

`shouldWrapChildren`