Tooltip

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

Code

import {
  Button,
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" />}>
        Hover
      </TooltipTrigger>
      <TooltipContent>
        <p>View product details</p>
      </TooltipContent>
    </Tooltip>
  );
}

FalconProvider includes TooltipProvider at the application root. See Getting started.

Composition

Use the following composition to build a Tooltip:

Tooltip
├── TooltipTrigger
└── TooltipContent

Side

Use the side prop to change the position of the tooltip.

Code

import {
  Button,
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:h-64 tw:flex-wrap tw:content-center tw:justify-center tw:gap-2">
      {(["left", "top", "bottom", "right"] as const).map((side) => (
        <Tooltip key={side}>
          <TooltipTrigger
            render={
              <Button variant="outline" className="tw:w-fit tw:capitalize" />
            }
          >
            {side}
          </TooltipTrigger>
          <TooltipContent side={side}>
            <p>View product details</p>
          </TooltipContent>
        </Tooltip>
      ))}
    </div>
  );
}

With Keyboard Shortcut

Code

import {
  Button,
  SaveIcon,
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger
        aria-label="Save order"
        render={<Button variant="outline" size="icon-sm" />}
      >
        <SaveIcon />
      </TooltipTrigger>
      <TooltipContent>
        Save order
        <kbd className="tw:rounded-sm tw:border tw:border-border tw:bg-muted tw:px-1.5 tw:py-0.5 tw:text-xs tw:text-muted-foreground">
          S
        </kbd>
      </TooltipContent>
    </Tooltip>
  );
}

Disabled Button

Show a tooltip on a disabled button by wrapping it with a focusable span. Keep the unavailable reason in persistent text because tooltip content is visual-only.

Code

import {
  Button,
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <>
      <Tooltip>
        <TooltipTrigger
          aria-describedby="ordering-unavailable-reason"
          aria-label="Order"
          render={<span className="tw:inline-block tw:w-fit" tabIndex={0} />}
        >
          <Button variant="outline" disabled>
            Order
          </Button>
        </TooltipTrigger>
        <TooltipContent>
          <p>Ordering is currently unavailable</p>
        </TooltipContent>
      </Tooltip>
      <p
        id="ordering-unavailable-reason"
        className="tw:mt-2 tw:text-sm tw:text-muted-foreground"
      >
        Ordering is currently unavailable
      </p>
    </>
  );
}

API

Tooltip

Groups a tooltip’s parts without rendering an HTML element. Tooltips must not contain essential information.

Props

children

children?: React.ReactNode

The content of the tooltip.

defaultOpen

defaultOpen?: boolean

Whether the tooltip is initially open. Defaults to false.

defaultTriggerId

defaultTriggerId?: string | null

ID of the trigger associated with an initially open tooltip.

disabled

disabled?: boolean

Whether the tooltip is disabled. Defaults to false.

disableHoverablePopup

disableHoverablePopup?: boolean

Whether moving the pointer onto the tooltip is prevented from keeping it open. Defaults to false.

onOpenChange

onOpenChange?: ((open: boolean, eventDetails: TooltipPrimitive.Root.ChangeEventDetails) => void)

Event handler called when the tooltip is opened or closed.

onOpenChangeComplete

onOpenChangeComplete?: ((open: boolean) => void)

Event handler called after tooltip animations complete.

open

open?: boolean

Whether the tooltip is currently open.

trackCursorAxis

trackCursorAxis?: "x" | "y" | "none" | "both"

Determines which axis the tooltip tracks the cursor on. Defaults to "none".

triggerId

triggerId?: string | null

ID of the trigger associated with a controlled tooltip.

TooltipContent

Includes a portal, positioned tooltip, and arrow. Renders a <div> element by default and accepts standard <div> props. Use render to replace the element.

Props

align

align?: Align = "center"

The alignment of the tooltip relative to its trigger. Defaults to "center".

alignOffset

alignOffset?: number | OffsetFunction = 0

The offset from the aligned position, in pixels. Defaults to 0.

anchor

anchor?: Element | VirtualElement | React.RefObject<Element | null> | (() => Element | VirtualElement | null) | null

Anchor used to position the tooltip instead of its trigger.

className

className?: string

CSS class applied to the tooltip.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>

Allows replacing the tooltip element or composing it with another component.

side

side?: Side = "top"

The side of the trigger where the tooltip is placed. Defaults to "top".

sideOffset

sideOffset?: number | OffsetFunction = 4

The offset from the trigger, in pixels. Defaults to 4.

style

style?: React.CSSProperties | ((state: TooltipPopupState) => React.CSSProperties | undefined)

Style applied to the tooltip, or a function based on its state.

TooltipProvider

Provides shared tooltip delay behavior for its descendants without rendering an HTML element.

Props

children

children?: React.ReactNode

Tooltips that share the provider’s delay behavior.

closeDelay

closeDelay?: number

How long to wait before closing a tooltip, in milliseconds. Defaults to 0.

delay

delay?: number = 0

How long to wait before opening a tooltip, in milliseconds. Defaults to 0.

timeout

timeout?: number

Time during which an adjacent tooltip opens instantly. Defaults to 400.

TooltipTrigger

Opens the associated tooltip. Renders a <button> element by default and accepts standard <button> props. Use render to replace the element.

Props

className

className?: string | ((state: TooltipTriggerState) => string | undefined)

CSS class applied to the trigger, or a function based on its state.

closeDelay

closeDelay?: number

How long to wait before closing the tooltip, in milliseconds. Defaults to 0.

closeOnClick

closeOnClick?: boolean

Whether the tooltip closes when the trigger is clicked. Defaults to true.

delay

delay?: number

How long to wait before opening the tooltip, in milliseconds. Defaults to the provider delay, or 600 without a provider.

disabled

disabled?: boolean

Whether interacting with the trigger is prevented from opening the tooltip. Defaults to false.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipTriggerState>

Allows replacing the trigger element or composing it with another component.

style

style?: React.CSSProperties | ((state: TooltipTriggerState) => React.CSSProperties | undefined)

Style applied to the trigger, or a function based on its state.