Tooltip

Hover/focus hint built on Base UI Tooltip.

import { SaveIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipDemo() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" />}>
        <SaveIcon data-icon="inline-start" />
        Save draft
      </TooltipTrigger>
      <TooltipContent>
        <p>Drafts are kept for 30 days</p>
      </TooltipContent>
    </Tooltip>
  )
}

Installation

pnpm dlx shadcn@latest add https://rdf.dev.360online.com/r/tooltip.json

Installs to @/components/ui/tooltip.

Manual installation

Install the dependencies:

pnpm add @base-ui/react@^1.8.0

Copy the source into your project:

components/ui/tooltip.tsx

'use client'

import { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip'
import { cn } from '@/lib/utils'

function TooltipProvider({ delay = 0, ...props }: TooltipPrimitive.Provider.Props) {
	return <TooltipPrimitive.Provider data-slot="tooltip-provider" delay={delay} {...props} />
}

function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
	return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
}

function TooltipTrigger({ className, ...props }: TooltipPrimitive.Trigger.Props) {
	return (
		<TooltipPrimitive.Trigger
			data-slot="tooltip-trigger"
			className={cn('focus-visible:ring-3 focus-visible:ring-ring focus-visible:outline-hidden', className)}
			{...props}
		/>
	)
}

function TooltipContent({
	className,
	side = 'top',
	sideOffset = 4,
	align = 'center',
	alignOffset = 0,
	children,
	...props
}: TooltipPrimitive.Popup.Props &
	Pick<TooltipPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset'>) {
	return (
		<TooltipPrimitive.Portal>
			<TooltipPrimitive.Positioner
				align={align}
				alignOffset={alignOffset}
				side={side}
				sideOffset={sideOffset}
				className="isolate z-50"
			>
				<TooltipPrimitive.Popup
					data-slot="tooltip-content"
					className={cn(
						'z-50 inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-md bg-popover px-3 py-1.5 text-xs text-popover-foreground ring-1 ring-border has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
						className,
					)}
					{...props}
				>
					{children}
					<TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-popover fill-popover data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
				</TooltipPrimitive.Popup>
			</TooltipPrimitive.Positioner>
		</TooltipPrimitive.Portal>
	)
}

export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger }

A tooltip component that displays additional information when hovering over or focusing on an element. Built on top of Base UI Tooltip, it follows WAI-ARIA design patterns and provides a consistent way to show supplementary information.

Features

Accessible tooltip implementation
Customizable open and close delay
Multiple positioning options
Keyboard navigation support
Screen reader announcements
Custom content support
Controlled and uncontrolled modes
Focus management
Hover and focus interactions
Popover-coloured surface with a subtle border and an arrow
Inline keyboard shortcuts with Kbd
Requires a TooltipProvider ancestor (typically once at the app root)

Usage

Tooltip no longer renders its own TooltipProvider. Wrap your application (or the relevant subtree) in a single TooltipProvider; it defaults to delay={0}.

Pass the trigger element with the render prop (Base UI has no asChild): <TooltipTrigger render={<Button variant="outline" />}>Save draft</TooltipTrigger>.

import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from '@/components/ui/tooltip'
import { Button } from '@/components/ui/button'
import { Kbd } from '@/components/ui/kbd'
import { SaveIcon } from 'lucide-react'

// Basic usage
export function BasicTooltip() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" />}>Save draft</TooltipTrigger>
        <TooltipContent>
          <p>Drafts are kept for 30 days</p>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

// With custom delay (per trigger, or for all tooltips via TooltipProvider)
export function DelayedTooltip() {
  return (
    <Tooltip>
      <TooltipTrigger delay={1000} render={<Button variant="outline" />}>Print</TooltipTrigger>
      <TooltipContent>
        <p>Prints the case summary</p>
      </TooltipContent>
    </Tooltip>
  )
}

// With keyboard shortcut
export function ShortcutTooltip() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" size="icon-sm" aria-label="Save" />}>
          <SaveIcon />
        </TooltipTrigger>
      <TooltipContent side="bottom">
        Save changes <Kbd>⌘S</Kbd>
      </TooltipContent>
    </Tooltip>
  )
}

// With rich content
export function RichTooltip() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" />}>Sofia Berg</TooltipTrigger>
        <TooltipContent>
          <div className="space-y-2">
            <p className="font-medium">Sofia Berg</p>
            <p className="text-muted-foreground">Case handler, building permits</p>
          </div>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

Examples

A short hint on an outline button.

With Icon

A case toolbar of icon-only buttons. Each has an aria-label, and the tooltip shows the same text to sighted users.

import { ArchiveIcon, DownloadIcon, PrinterIcon, Share2Icon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipWithIcon() {
  const actions = [
    { label: 'Print', icon: PrinterIcon },
    { label: 'Download as PDF', icon: DownloadIcon },
    { label: 'Share with a colleague', icon: Share2Icon },
    { label: 'Move to archive', icon: ArchiveIcon },
  ]
  return (
    <div className="flex items-center gap-1 rounded-lg border p-1" role="toolbar" aria-label="Case 2026-04812">
      {actions.map(({ label, icon: Icon }) => (
        <Tooltip key={label}>
          <TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label={label} />}>
            <Icon />
          </TooltipTrigger>
          <TooltipContent side="bottom">{label}</TooltipContent>
        </Tooltip>
      ))}
    </div>
  )
}

Custom Delay

delay per trigger (or for all tooltips on TooltipProvider). The provider defaults to 0.

import { Button } from '@/components/ui/button'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipCustomDelay() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      {[0, 500, 1000].map((delay) => (
        <Tooltip key={delay}>
          <TooltipTrigger delay={delay} render={<Button variant="outline" />}>
            {delay === 0 ? 'Instant' : `${delay} ms`}
          </TooltipTrigger>
          <TooltipContent>
            <p>Opened after {delay} ms</p>
          </TooltipContent>
        </Tooltip>
      ))}
    </div>
  )
}

Rich Content

Several lines of content – the name, role and availability of each handler on a case.

import { UserPlusIcon } from 'lucide-react'
import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup } from '@/components/ui/avatar'
import { Button } from '@/components/ui/button'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipWithHTML() {
  const team = [
    { initials: 'SB', name: 'Sofia Berg', role: 'Case handler, building permits', status: 'Available' },
    { initials: 'MV', name: 'Mikko Virtanen', role: 'Building inspector', status: 'In a site visit until 14:00' },
    { initials: 'OH', name: 'Omar Haddad', role: 'Legal advisor', status: 'Away until 22 April' },
  ]
  return (
    <div className="flex items-center gap-3">
      <AvatarGroup>
        {team.map((person) => (
          <Tooltip key={person.initials}>
            <TooltipTrigger className="rounded-full">
              <Avatar>
                <AvatarFallback>{person.initials}</AvatarFallback>
                {person.status === 'Available' ? <AvatarBadge /> : null}
              </Avatar>
              <span className="sr-only">{person.name}</span>
            </TooltipTrigger>
            <TooltipContent>
              <div className="flex flex-col gap-0.5">
                <p className="font-medium">{person.name}</p>
                <p className="text-muted-foreground">{person.role}</p>
                <p className="text-muted-foreground">{person.status}</p>
              </div>
            </TooltipContent>
          </Tooltip>
        ))}
      </AvatarGroup>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="icon-sm" aria-label="Add handler to case" />}>
          <UserPlusIcon />
        </TooltipTrigger>
        <TooltipContent>Add handler to case</TooltipContent>
      </Tooltip>
    </div>
  )
}

A plain-text trigger inside running text that explains an abbreviation. Long content wraps at max-w-xs.

import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipPlainTooltip() {
  return (
    <p className="max-w-md text-sm leading-relaxed text-muted-foreground">
      Your application is assessed under the{' '}
      <Tooltip>
        <TooltipTrigger className="cursor-help rounded-sm font-medium text-foreground underline decoration-dotted underline-offset-4">
          PBL
        </TooltipTrigger>
        <TooltipContent>
          The Planning and Building Act (2010:900), which regulates detailed plans, building permits and demolition permits
          in the municipality.
        </TooltipContent>
      </Tooltip>{' '}
      and the detailed plan for Ekdalen. We aim to decide within 10 weeks of receiving a complete application.
    </p>
  )
}

Sides

Place the tooltip with side: top, right, bottom or left.

import { Button } from '@/components/ui/button'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipSides() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      {(['top', 'right', 'bottom', 'left'] as const).map((side) => (
        <Tooltip key={side}>
          <TooltipTrigger render={<Button variant="outline" className="capitalize" />}>{side}</TooltipTrigger>
          <TooltipContent side={side}>
            <p>Shown on the {side}</p>
          </TooltipContent>
        </Tooltip>
      ))}
    </div>
  )
}

With Keyboard Shortcut

Kbd and KbdGroup inside the content get tooltip-specific styling. Mirror the shortcut in aria-keyshortcuts.

import { SaveIcon, SearchIcon, UndoIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { Kbd, KbdGroup } from '@/components/ui/kbd'
import { Separator } from '@/components/ui/separator'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipWithKeyboardShortcut() {
  return (
    <div className="flex items-center gap-1 rounded-lg border p-1" role="toolbar" aria-label="Editor">
      <Tooltip>
        <TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Save" aria-keyshortcuts="Meta+S" />}>
          <SaveIcon />
        </TooltipTrigger>
        <TooltipContent>
          Save <Kbd>⌘S</Kbd>
        </TooltipContent>
      </Tooltip>
      <Tooltip>
        <TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Undo" aria-keyshortcuts="Meta+Z" />}>
          <UndoIcon />
        </TooltipTrigger>
        <TooltipContent>
          Undo <Kbd>⌘Z</Kbd>
        </TooltipContent>
      </Tooltip>
      <Separator orientation="vertical" className="mx-1 h-4" />
      <Tooltip>
        <TooltipTrigger
          render={<Button variant="ghost" size="icon-sm" aria-label="Search cases" aria-keyshortcuts="Meta+Shift+F" />}
        >
          <SearchIcon />
        </TooltipTrigger>
        <TooltipContent>
          Search cases
          <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>⇧</Kbd>
            <Kbd>F</Kbd>
          </KbdGroup>
        </TooltipContent>
      </Tooltip>
    </div>
  )
}

Disabled Button

A disabled button can't be focused or hovered, so its tooltip never shows. Use aria-disabled="true" instead: the button stays focusable, the tooltip explains why the action is unavailable, and the click handler does nothing.

import { Button } from '@/components/ui/button'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipDisabledButton() {
  return (
    <Tooltip>
      <TooltipTrigger
        render={
          <Button
            aria-disabled="true"
            className="cursor-not-allowed opacity-50 hover:bg-primary active:bg-primary"
            onClick={(event) => event.preventDefault()}
          />
        }
      >
        Submit application
      </TooltipTrigger>
      <TooltipContent>
        <p>Attach the site plan before you submit</p>
      </TooltipContent>
    </Tooltip>
  )
}

Field Hint

A small info button next to a field label, with guidance on where to find the value.

import { InfoIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { Field, FieldLabel } from '@/components/ui/field'
import { Input } from '@/components/ui/input'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

export function TooltipFieldHint() {
  return (
    <Field className="w-full max-w-xs">
      <div className="flex items-center gap-1">
        <FieldLabel htmlFor="tooltip-property">Property designation</FieldLabel>
        <Tooltip>
          <TooltipTrigger
            render={<Button variant="ghost" size="icon-xs" aria-label="Where do I find the property designation?" />}
          >
            <InfoIcon />
          </TooltipTrigger>
          <TooltipContent side="right">
            Shown on your property tax notice and in the land register, for example Ekdalen 4:12.
          </TooltipContent>
        </Tooltip>
      </div>
      <Input id="tooltip-property" placeholder="Ekdalen 4:12" />
    </Field>
  )
}

Props

TooltipProvider

delay - Delay in ms before tooltips open (default 0)
closeDelay - Delay in ms before tooltips close
timeout - Time in ms during which moving to another trigger opens its tooltip instantly

open / defaultOpen / onOpenChange - Open state
disabled - Stops the tooltip from opening

TooltipTrigger

render - The element to render as the trigger, e.g. render={<Button variant="outline" />} (replaces asChild)
delay / closeDelay - Override the provider delays for this trigger
closeOnClick - Whether clicking the trigger closes the tooltip (default true)

TooltipContent

side - 'top' | 'right' | 'bottom' | 'left' | 'inline-start' | 'inline-end' (default 'top')
sideOffset - Distance from the trigger (default 4)
align / alignOffset - Alignment relative to the trigger
className - Additional CSS classes

Accessibility

The Tooltip component follows WAI-ARIA guidelines for tooltips:

Uses role="tooltip" for proper semantic meaning
Manages focus appropriately
Supports keyboard navigation
Announces content to screen readers
Provides sufficient contrast for visibility
Maintains proper timing for display

Best Practices

Keep tooltip content concise and helpful
Use tooltips sparingly to avoid overwhelming users
Ensure tooltip content adds value beyond what's visible
Consider mobile users and touch interactions
Test with keyboard navigation and screen readers
Maintain appropriate delay duration for user experience
Use consistent styling across your application

Tooltip

Installation

Features

Usage

Examples

Default Tooltip

With Icon

Custom Delay

Rich Content

Plain Tooltip

Sides

With Keyboard Shortcut

Disabled Button

Field Hint

Props

TooltipProvider

Tooltip

TooltipTrigger

TooltipContent

Accessibility

Best Practices