On this page

Tooltip Primitive

Tooltip is a Starwind Runtime primitive in the presence-floating-overlay contract family.

Anatomy

Use the Astro primitive adapter to render Tooltip anatomy with the Runtime wiring included.

---
import { Tooltip } from "@starwind-ui/astro/tooltip";
---

<Tooltip.Root>
  <Tooltip.Trigger>Hover me</Tooltip.Trigger>
  <Tooltip.Positioner>
    <Tooltip.Popup>
      <Tooltip.Arrow />
    </Tooltip.Popup>
  </Tooltip.Positioner>
</Tooltip.Root>

Use the React primitive adapter when Tooltip state participates in React rendering.

import { Tooltip } from "@starwind-ui/react/tooltip";

export function Example() {
  return (
    <Tooltip.Root>
      <Tooltip.Trigger>Hover me</Tooltip.Trigger>
      <Tooltip.Positioner>
        <Tooltip.Popup>
          <Tooltip.Arrow />
        </Tooltip.Popup>
      </Tooltip.Positioner>
    </Tooltip.Root>
  );
}

Render the Tooltip data-sw-* contract yourself, then initialize createTooltip.

<div data-sw-tooltip>
  <button data-sw-tooltip-trigger type="button">Hover me</button>
  <div data-sw-tooltip-positioner>
    <div data-sw-tooltip-popup role="tooltip" hidden>
      <div data-sw-tooltip-arrow></div>
    </div>
  </div>
</div>

<script type="module">
  import { createTooltip } from "@starwind-ui/runtime/tooltip";

  const root = document.querySelector("[data-sw-tooltip]");
  if (root) {
    createTooltip(root);
  }
</script>

Floating Behavior

Fact	Value
Anchor part	trigger
Positioner part	positioner
Popup part	popup
Portal part	portal
Option props	side, align, sideOffset, avoidCollisions

API Reference

Root

The main element that owns the Tooltip Runtime instance.

Default element: div
Discovery hook: data-sw-tooltip
Role: -

Props

Prop Type Default

open boolean -

Description: Controls whether Tooltip is open.
Kind: control
Targets: root
Full type: boolean

defaultOpen boolean false

Description: Sets whether Tooltip starts open.
Kind: control
Targets: root
Full type: boolean

closeDelay number 200

Description: Sets how long Tooltip waits before closing.
Kind: option
Targets: -
Full type: number

closeOnEscape boolean true

Description: Closes Tooltip when Escape is pressed.
Kind: option
Targets: -
Full type: boolean

closeOnOutsideInteract boolean true

Description: Closes Tooltip when the user interacts outside it.
Kind: option
Targets: -
Full type: boolean

disabled boolean false

Description: Disables the Root part.
Kind: option
Targets: -
Full type: boolean

disableHoverableContent boolean false

Description: Configures the disable hoverable content option for the Root part.
Kind: option
Targets: root
Full type: boolean

openDelay number 200

Description: Sets how long Tooltip waits before opening.
Kind: option
Targets: -
Full type: number

onOpenChange (open: boolean, details: TooltipOpenChangeDetails) => void -

Description: Runs when Tooltip opens or closes.
Kind: callback
Targets: -
Full type: (open: boolean, details: TooltipOpenChangeDetails) => void

Events

Event Callback Value

openChange onOpenChange open: boolean

Description: Fires when Tooltip opens or closes.
DOM event: starwind:open-change
Details type: TooltipOpenChangeDetails
Timing: before-state-commit
Cancelable: Yes

State

State Type Props

open boolean open / defaultOpen

Description: Tracks whether Tooltip is open.
Initial attribute: data-default-open
Runtime getter: getOpen
Runtime setter: setOpen
State control support: React supports controlled and default state with open and defaultOpen props. Runtime/HTML reads initial state from data-default-open, emits starwind:open-change, and updates with setOpen. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tooltip - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Root part.

Metadata

Attribute Value Description

data-default-open - Reflects the default open prop on the Root part.

data-close-delay - Reflects the close delay prop on the Root part.

data-close-on-escape - Reflects the close on escape prop on the Root part.

data-close-on-outside-interact - Reflects the close on outside interact prop on the Root part.

data-content-hoverable - Reflects the content hoverable prop on the Root part.

data-disabled - Reflects the disabled prop on the Root part.

data-open-delay - Reflects the open delay prop on the Root part.

Trigger

The control that opens, closes, or targets the Tooltip content.

Default element: button
Discovery hook: data-sw-tooltip-trigger
Role: -

Props

Prop Type Default

asChild boolean -

Description: Merges behavior onto your child element instead of rendering the default Trigger element.
Kind: rendering
Targets: trigger
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tooltip-trigger - Marks the Trigger part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Trigger part.

Metadata

Attribute Value Description

data-as-child - Reflects the as child prop on the Trigger part.

data-disabled - Reflects the disabled prop on the Trigger part.

Portal

Moves Tooltip overlay content to the document body when needed.

Default element: div
Discovery hook: data-sw-tooltip-portal
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tooltip-portal - Marks the Portal part so Starwind Runtime can find it.

Positioner

Positions the Tooltip content relative to its trigger.

Default element: div
Discovery hook: data-sw-tooltip-positioner
Role: -

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "top"

Description: Sets the preferred side for Tooltip content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "center"

Description: Sets how Tooltip content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 8

Description: Sets the distance between Tooltip content and its trigger.
Kind: option
Targets: positioner, popup
Full type: number

avoidCollisions boolean true

Description: Allows Tooltip content to shift or flip to stay visible.
Kind: option
Targets: positioner, popup
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tooltip-positioner - Marks the Positioner part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Positioner part.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Positioner part.

data-align - Reflects the align prop on the Positioner part.

data-side-offset - Reflects the side offset prop on the Positioner part.

data-avoid-collisions - Reflects the avoid collisions prop on the Positioner part.

The floating content container for Tooltip.

Default element: div
Discovery hook: data-sw-tooltip-popup
Role: tooltip

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "top"

Description: Sets the preferred side for Tooltip content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "center"

Description: Sets how Tooltip content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 8

Description: Sets the distance between Tooltip content and its trigger.
Kind: option
Targets: positioner, popup
Full type: number

avoidCollisions boolean true

Description: Allows Tooltip content to shift or flip to stay visible.
Kind: option
Targets: positioner, popup
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tooltip-popup - Marks the Popup part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Popup part.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Popup part.

data-align - Reflects the align prop on the Popup part.

data-side-offset - Reflects the side offset prop on the Popup part.

data-avoid-collisions - Reflects the avoid collisions prop on the Popup part.

Arrow

The arrow element that visually points to the trigger.

Default element: div
Discovery hook: data-sw-tooltip-arrow
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tooltip-arrow - Marks the Arrow part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Arrow part.

Runtime API

Factory: createTooltip
Import: @starwind-ui/runtime/tooltip
Root hook: root data-sw-tooltip
Option props: closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disabled, disableHoverableContent, onOpenChange, open, openDelay

Option Lifecycles

Option	Lifecycle
closeDelay	constructor-only
closeOnEscape	constructor-only
closeOnOutsideInteract	constructor-only
defaultOpen	constructor-only
disabled	setter-backed
disableHoverableContent	constructor-only
onOpenChange	constructor-only
open	setter-backed
openDelay	constructor-only

Runtime Setters

Method Target Description

setOpen state: open Opens or closes Tooltip from Runtime code.

setDisabled prop: disabled Updates whether Tooltip is disabled from Runtime code.

Component Relationship

Tooltip Direct primitive

Layer Metadata

Tooltip Primitive uses createTooltip. Styled components: Tooltip.

primitive Tooltip Primitive Tooltip Primitive uses createTooltip. Styled components: Tooltip. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters tooltip Tooltip Presence Floating Overlay Overlays that combine open state, portal structure, and floating placement. /docs/primitives/tooltip/ createTooltip @starwind-ui/runtime/tooltip /docs/runtime/#create-tooltip root closeDelay closeOnEscape closeOnOutsideInteract defaultOpen disabled disableHoverableContent onOpenChange open openDelay raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Tooltip data-sw-* contract yourself, then initialize createTooltip. html Use the Astro primitive adapter to render Tooltip anatomy with the Runtime wiring included. Use the React primitive adapter when Tooltip state participates in React rendering. tsx div data-sw-tooltip boolean Controls whether Tooltip is open. Sets whether Tooltip starts open. number Sets how long Tooltip waits before closing. Closes Tooltip when Escape is pressed. Closes Tooltip when the user interacts outside it. Disables the Root part. Configures the disable hoverable content option for the Root part. Sets how long Tooltip waits before opening. (open: boolean, details: TooltipOpenChangeDetails) => void TooltipOpenChangeDetails Runs when Tooltip opens or closes. runtime Marks the Root part so Starwind Runtime can find it. data-default-open prop Reflects the default open prop on the Root part. data-close-delay Reflects the close delay prop on the Root part. data-close-on-escape Reflects the close on escape prop on the Root part. data-close-on-outside-interact Reflects the close on outside interact prop on the Root part. data-content-hoverable Reflects the content hoverable prop on the Root part. data-disabled Reflects the disabled prop on the Root part. data-open-delay Reflects the open delay prop on the Root part. data-state state Reflects the current state on the Root part. getOpen setOpen openChange starwind:open-change setDisabled trigger button data-sw-tooltip-trigger asChild Merges behavior onto your child element instead of rendering the default Trigger element. Marks the Trigger part so Starwind Runtime can find it. data-as-child Reflects the as child prop on the Trigger part. Reflects the disabled prop on the Trigger part. Reflects the current state on the Trigger part. portal data-sw-tooltip-portal Marks the Portal part so Starwind Runtime can find it. positioner data-sw-tooltip-positioner side "top" | "right" | "bottom" | "left" Sets the preferred side for Tooltip content. align "start" | "center" | "end" Sets how Tooltip content aligns to its trigger. sideOffset Sets the distance between Tooltip content and its trigger. avoidCollisions Allows Tooltip content to shift or flip to stay visible. Marks the Positioner part so Starwind Runtime can find it. Reflects the current state on the Positioner part. data-side Reflects the side prop on the Positioner part. data-align Reflects the align prop on the Positioner part. data-side-offset Reflects the side offset prop on the Positioner part. data-avoid-collisions Reflects the avoid collisions prop on the Positioner part. popup data-sw-tooltip-popup Marks the Popup part so Starwind Runtime can find it. Reflects the current state on the Popup part. Reflects the side prop on the Popup part. Reflects the align prop on the Popup part. Reflects the side offset prop on the Popup part. Reflects the avoid collisions prop on the Popup part. arrow data-sw-tooltip-arrow Marks the Arrow part so Starwind Runtime can find it. Reflects the current state on the Arrow part. Root Trigger type aria-disabled Portal Positioner Popup role hidden Arrow @starwind-ui/astro @starwind-ui/astro/tooltip Render static closed tooltip anatomy and self-initialize; runtime owns hover/focus timers, portal movement, and floating updates. @starwind-ui/react @starwind-ui/react/tooltip Create the controller with creation-time timing/dismissal options and bridge controlled open state through setOpen. /docs/components/tooltip/ Direct primitive direct-primitive Styled component Tooltip

Tooltip Primitive

Anatomy

Floating Behavior

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Trigger

Props

Data Attributes

Runtime hooks

State

Metadata

Portal

Data Attributes

Runtime hooks

Positioner

Props

Data Attributes

Runtime hooks

State

Metadata

Popup

Props

Data Attributes

Runtime hooks

State

Metadata

Arrow

Data Attributes

Runtime hooks

State

Runtime API

Option Lifecycles

Runtime Setters

Related Styled Components