Tooltip

Tooltip only appears on mouse hover or keyboard focus and contain a label or description text. Use tooltips sparingly and as a last resort. Consider these alternatives.

When using a tooltip, follow the provided guidelines to avoid accessibility issues:

• Tooltip text should be brief and to the point.
• Tooltips should contain only non-essential text. Tooltips can easily be missed and are not accessible on touch devices so never use tooltips to convey critical information.

Examples

As a description for icon-only button

If the tooltip content provides supplementary description, wrap the target in a Tooltip. The trigger element should also have a concise accessible label via aria-label.

<Tooltip text="Directly mention a team or user">
  <IconButton aria-label="Mentions" icon={MentionIcon} variant="invisible" />
</Tooltip>

As a description for a button with visible label

<Tooltip text="This will immediately impact all organization members">
  <Button variant="primary">Save</Button>
</Tooltip>

With direction

Set direction of tooltip with direction. The tooltip is responsive and will automatically adjust direction to avoid cutting off.

<Box
  sx={{
    display: 'flex',
    flexDirection: 'column',
    gap: 8,
    marginY: 4,
    '[data-component=tooltip]': {visibility: 'visible', opacity: 1}
  }}
>
  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
    <Tooltip direction="nw" text="Tooltip text">
      <Button>North west</Button>
    </Tooltip>
    <Tooltip direction="n" text="Tooltip text">
      <Button>North</Button>
    </Tooltip>
    <Tooltip direction="ne" text="Tooltip text">
      <Button>North east</Button>
    </Tooltip>
  </Box>
  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
    <Tooltip direction="e" text="Tooltip text">
      <Button>East</Button>
    </Tooltip>
    <Tooltip direction="w" text="Tooltip text">
      <Button>West</Button>
    </Tooltip>
  </Box>
  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
    <Tooltip direction="sw" text="Tooltip text">
      <Button>South west</Button>
    </Tooltip>
    <Tooltip direction="s" text="Tooltip text">
      <Button>South</Button>
    </Tooltip>
    <Tooltip direction="se" text="Tooltip text">
      <Button>South east</Button>
    </Tooltip>
  </Box>
</Box>

Props

Tooltip

React.ReactNode

string

string

'description' | 'label'

'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w'

'left' | 'right'

boolean

boolean

SystemStyleObject

Status

Alpha

• Component props are documented on primer.style/react.
• Component does not have any unnecessary third-party dependencies.
• Component can adapt to different themes.
• Component can adapt to different screen sizes.
• Component has 100% test coverage.

Beta

• Component is used in a production application.
• Common usage examples are documented on primer.style/react.
• Common usage examples are documented in storybook stories.
• Component has been reviewed by a systems designer and any resulting issues have been addressed.
• Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Stable

• Component API has been stable with no breaking changes for at least one month.
• Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
• Component has corresponding design guidelines documented in the interface guidelines.
• Component has corresponding Figma component in the Primer Web library.

Further reading

• Tooltip alternatives

Related components

• IconButton