Skip to main content

​
Tooltip

The Tooltip component provides contextual information or labels for elements when users interact with them. It’s useful for explaining icon buttons, showing additional details, or providing helpful hints.

​
Installation

npm install @naturacosmeticos/natds-web

​
Usage

import { Tooltip, Button } from '@naturacosmeticos/natds-web';

function BasicTooltip() {
  return (
    <Tooltip title="This is a helpful tooltip">
      <Button>Hover me</Button>
    </Tooltip>
  );
}

​
Tooltip Placements

​
Top Placement (Default)

<Tooltip title="Tooltip on top" placement="top">
  <Button>Top</Button>
</Tooltip>

​
Bottom Placement

<Tooltip title="Tooltip on bottom" placement="bottom">
  <Button>Bottom</Button>
</Tooltip>

​
Left Placement

<Tooltip title="Tooltip on left" placement="left">
  <Button>Left</Button>
</Tooltip>

​
Right Placement

<Tooltip title="Tooltip on right" placement="right">
  <Button>Right</Button>
</Tooltip>

​
All Placement Options

function AllPlacements() {
  const placements = [
    'top-start', 'top', 'top-end',
    'left-start', 'left', 'left-end',
    'right-start', 'right', 'right-end',
    'bottom-start', 'bottom', 'bottom-end'
  ];

  return (
    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 16 }}>
      {placements.map((placement) => (
        <Tooltip key={placement} title={placement} placement={placement}>
          <Button>{placement}</Button>
        </Tooltip>
      ))}
    </div>
  );
}

​
Icon Button with Tooltip

import { Tooltip, IconButton, Icon } from '@naturacosmeticos/natds-web';

function IconWithTooltip() {
  return (
    <div style={{ display: 'flex', gap: 8 }}>
      <Tooltip title="Delete">
        <IconButton>
          <Icon name="outlined-action-delete" />
        </IconButton>
      </Tooltip>
      
      <Tooltip title="Edit">
        <IconButton>
          <Icon name="outlined-action-edit" />
        </IconButton>
      </Tooltip>
      
      <Tooltip title="Share">
        <IconButton>
          <Icon name="outlined-action-share" />
        </IconButton>
      </Tooltip>
      
      <Tooltip title="More options">
        <IconButton>
          <Icon name="outlined-navigation-more" />
        </IconButton>
      </Tooltip>
    </div>
  );
}

​
Controlled Tooltip

Manually control when the tooltip is visible: 
function ControlledTooltip() {
  const [open, setOpen] = React.useState(false);

  return (
    <div>
      <Button onClick={() => setOpen(!open)}>
        Toggle Tooltip
      </Button>
      
      <Tooltip 
        title="Controlled tooltip" 
        open={open}
        onClose={() => setOpen(false)}
        onOpen={() => setOpen(true)}
      >
        <Button style={{ marginLeft: 16 }}>Target Element</Button>
      </Tooltip>
    </div>
  );
}

​
Arrow Tooltip

Add an arrow pointing to the target element: 
<Tooltip title="Tooltip with arrow" arrow>
  <Button>Hover me</Button>
</Tooltip>

​
Interactive Tooltip

Allow users to interact with tooltip content: 
<Tooltip 
  title={
    <div>
      <p>Interactive tooltip</p>
      <Button size="small" onClick={() => alert('Clicked!')}>Click me</Button>
    </div>
  }
  interactive
>
  <Button>Hover for interactive content</Button>
</Tooltip>

​
Custom Delay

Control when the tooltip appears and disappears: 
<div style={{ display: 'flex', gap: 16 }}>
  <Tooltip title="Fast" enterDelay={0} leaveDelay={0}>
    <Button>Fast</Button>
  </Tooltip>
  
  <Tooltip title="Normal" enterDelay={500} leaveDelay={200}>
    <Button>Normal</Button>
  </Tooltip>
  
  <Tooltip title="Slow" enterDelay={1000} leaveDelay={500}>
    <Button>Slow</Button>
  </Tooltip>
</div>

​
Disabled Elements

Tooltips on disabled elements require a wrapper: 
<Tooltip title="This button is disabled">
  <span>
    <Button disabled>Disabled Button</Button>
  </span>
</Tooltip>

​
Rich Content Tooltip

function RichTooltip() {
  return (
    <Tooltip
      title={
        <div>
          <Typography variant="subtitle2">Rich Content</Typography>
          <Typography variant="body2" style={{ marginTop: 4 }}>
            Tooltips can contain multiple lines and formatted text.
          </Typography>
          <ul style={{ margin: 0, paddingLeft: 20 }}>
            <li>Feature 1</li>
            <li>Feature 2</li>
            <li>Feature 3</li>
          </ul>
        </div>
      }
      interactive
    >
      <Button>Rich Tooltip</Button>
    </Tooltip>
  );
}

​
Toolbar with Tooltips

import { Toolbar, Tooltip, IconButton, Icon } from '@naturacosmeticos/natds-web';

function ToolbarExample() {
  return (
    <Toolbar>
      <Tooltip title="Save">
        <IconButton>
          <Icon name="outlined-action-save" />
        </IconButton>
      </Tooltip>
      
      <Tooltip title="Undo">
        <IconButton>
          <Icon name="outlined-action-undo" />
        </IconButton>
      </Tooltip>
      
      <Tooltip title="Redo">
        <IconButton>
          <Icon name="outlined-action-redo" />
        </IconButton>
      </Tooltip>
      
      <Tooltip title="Print">
        <IconButton>
          <Icon name="outlined-action-print" />
        </IconButton>
      </Tooltip>
    </Toolbar>
  );
}

​
Table Actions with Tooltips

function TableWithTooltips() {
  return (
    <Table>
      <TableHead>
        <TableRow>
          <TableCell>Name</TableCell>
          <TableCell>Status</TableCell>
          <TableCell>Actions</TableCell>
        </TableRow>
      </TableHead>
      <TableBody>
        <TableRow>
          <TableCell>John Doe</TableCell>
          <TableCell>Active</TableCell>
          <TableCell>
            <Tooltip title="Edit user">
              <IconButton size="small">
                <Icon name="outlined-action-edit" />
              </IconButton>
            </Tooltip>
            <Tooltip title="Delete user">
              <IconButton size="small">
                <Icon name="outlined-action-delete" />
              </IconButton>
            </Tooltip>
          </TableCell>
        </TableRow>
      </TableBody>
    </Table>
  );
}

​
Props

​
children
element
required
The element that triggers the tooltip. Must be a single React element that can accept a ref.
​
title
node
required
The tooltip content. Can be a string or React element.
​
placement
string
default:"'bottom'"
Tooltip placement. Options: ‘top’, ‘bottom’, ‘left’, ‘right’, and variations with ‘-start’ and ‘-end’.
​
arrow
boolean
default:"false"
If true, adds an arrow to the tooltip pointing to the reference element.
​
open
boolean
If provided, the tooltip is controlled and will be shown when true.
​
onClose
function
Callback fired when the tooltip requests to be closed.
​
onOpen
function
Callback fired when the tooltip requests to be opened.
​
enterDelay
number
default:"100"
The number of milliseconds to wait before showing the tooltip.
​
leaveDelay
number
default:"0"
The number of milliseconds to wait before hiding the tooltip.
​
interactive
boolean
default:"false"
If true, allows the user to interact with the tooltip content.
​
disableFocusListener
boolean
default:"false"
If true, the tooltip won’t show when the element receives focus.
​
disableHoverListener
boolean
default:"false"
If true, the tooltip won’t show on hover.
​
disableTouchListener
boolean
default:"false"
If true, the tooltip won’t show on touch.

​
Best Practices

  • Keep tooltip text concise (1-2 lines maximum)
  • Use tooltips to explain icon buttons without text labels
  • Don’t use tooltips for critical information
  • Ensure tooltips don’t cover important content
  • Avoid putting tooltips on disabled elements (use wrapper instead)
  • Use appropriate placement to avoid screen edges
  • Don’t rely on tooltips for mobile-only experiences
  • Keep enterDelay short for better UX (100-300ms)
  • Use arrow prop for better visual connection to target

​
Common Use Cases

  1. Icon Buttons: Explain what an icon button does
  2. Truncated Text: Show full text when space is limited
  3. Additional Info: Provide supplementary details
  4. Help Text: Offer contextual help
  5. Keyboard Shortcuts: Display available shortcuts
  6. Status Indicators: Explain status icons or badges

​
Accessibility

  • Tooltips are keyboard accessible (show on focus)
  • Content is announced by screen readers
  • Uses appropriate ARIA attributes automatically
  • Don’t hide critical information in tooltips
  • Ensure tooltip text is readable (good contrast)
  • Consider users who can’t hover (touch devices)
  • Provide alternative ways to access tooltip information

​
Important Notes

The children prop must be a single element that can accept a ref. If you need to wrap multiple elements or text, wrap them in a <span> or <div>.
// ❌ Wrong - Multiple children
<Tooltip title="Info">
  <Icon /> Text
</Tooltip>

// ✅ Correct - Single element
<Tooltip title="Info">
  <span>
    <Icon /> Text
  </span>
</Tooltip>

​
Performance Tips

  • Use enterDelay to prevent tooltips from appearing accidentally
  • Avoid complex content in tooltips for better performance
  • Don’t render hundreds of tooltips simultaneously
  • Consider lazy loading for interactive tooltip content

​
Related Components

  • IconButton - Commonly used with tooltips
  • Button - Can be wrapped with tooltips
  • Icon - Often needs tooltip explanation

Build docs developers (and LLMs) love

Get started for freeTalk to us