For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/tooltip.md.

Tooltip

Add a brief explanation to a page element.

Basic usage

Hover or keyboard focus shows the tooltip; Escape closes it. Keep content descriptive; use Popover for interactive content.

basic.tsx
import { Button, Tooltip } from '@ifhover/leaf-ui';

export function TooltipBasic() {
  return (
    <Tooltip content="Save changes to the current project">
      <Button variant="outline">Save</Button>
    </Tooltip>
  );
}

Examples

Placement

Set the preferred position with placement; it adjusts when space is limited.

Top
Bottom
Left
Right
placements.tsx
import { Button, Flex, Grid, Text, Tooltip } from '@ifhover/leaf-ui';

const placements = [
  { placement: 'top', label: 'Top' },
  { placement: 'bottom', label: 'Bottom' },
  { placement: 'left', label: 'Left' },
  { placement: 'right', label: 'Right' },
] as const;

export function TooltipPlacements() {
  return (
    <Flex direction="column" gap="md">
      {placements.map(({ placement, label }) => (
        <Grid
          key={placement}
          role="group"
          aria-label={label}
          columns={{ xs: 1, sm: 2 }}
          gap="8px"
          align="center"
        >
          <Text tone="muted">{label}</Text>
          <Tooltip placement={placement} content="Save changes to the current project">
            <Button variant="outline">Save</Button>
          </Tooltip>
        </Grid>
      ))}
    </Flex>
  );
}

Disabled tooltip

Tooltip's disabled only turns off the tooltip, not the button. A disabled button cannot receive focus; use a focusable wrapper to explain why it is disabled.

Default
Disabled tooltip
disabled.tsx
import { Button, Flex, Grid, Text, Tooltip } from '@ifhover/leaf-ui';

const states = [
  { disabled: false, label: 'Default' },
  { disabled: true, label: 'Disabled tooltip' },
];

export function TooltipDisabled() {
  return (
    <Flex direction="column" gap="md">
      {states.map(({ disabled, label }) => (
        <Grid
          key={label}
          role="group"
          aria-label={label}
          columns={{ xs: 1, sm: 2 }}
          gap="8px"
          align="center"
        >
          <Text tone="muted">{label}</Text>
          <Flex align="start">
            <Tooltip content="Save changes to the current project" disabled={disabled}>
              <Button variant="outline">Save</Button>
            </Tooltip>
          </Flex>
        </Grid>
      ))}
    </Flex>
  );
}

Controlled visibility

Manage visibility with open and onOpenChange. Without open, defaultOpen only sets the initial state.

controlled.tsx
import { Button, Flex, Tooltip } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TooltipControlled() {
  const [open, setOpen] = useState(false);
  return (
    <Flex gap="sm" align="center" wrap>
      <Tooltip
        content="This setting applies to the current project"
        open={open}
        onOpenChange={setOpen}
      >
        <Button variant="outline">View help</Button>
      </Tooltip>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Show tooltip
      </Button>
      <Button variant="outline" onClick={() => setOpen(false)}>
        Hide tooltip
      </Button>
    </Flex>
  );
}

API

Tooltip API

Configure hint content, placement and visibility behavior.

The trigger must forward its ref and events. Its existing aria-describedby is merged with the tooltip reference. See PopupOptions for shared popup options.

PropertyTypeDefaultDescription
contentReactNodeRequiredTooltip content; empty strings, null and undefined suppress the tooltip.
childrenReactElement< HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement>; disabled?: boolean } >RequiredTrigger element supporting a ref and events
placement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end''top'Preferred placement; adjusts when space is limited
arrowbooleantrueWhether to show the arrow pointing to the trigger.
disabledbooleanfalseSuppress the tooltip without disabling its trigger.
openboolean—Controlled open state.
defaultOpenbooleanfalseInitial open state for uncontrolled usage.
onOpenChange(open: boolean) => void—Open state change
enterDelaynumber100Delay in milliseconds before opening on hover.
leaveDelaynumber100Delay in milliseconds before closing after pointer leave.
classNamestring—Tooltip panel class
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—Placement relative to the trigger.
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—Custom popup styles.
popupRender(content: React.ReactNode) => React.ReactNode—Wrap or extend popup content; retain the supplied content to preserve interaction.
getPopupContainer() => Element | DocumentFragment—Return a popup container, including a ShadowRoot.