Overlays@knitui/components

Tooltip

Tooltip wraps a single target element and renders a floating label on hover (or focus/touch when enabled). Positioning is handled by floating-ui with automatic flip and shift on overflow.

WebiOSAndroid4 style slots23 own props12 examples

Stories Source Tests Open in Storybook

import { Tooltip } from "@knitui/components";

Playground

Loading playground…

labelFloating label content shown when the tooltip opens.

positionPreferred placement relative to the target element.

offsetMain-axis gap in px between the target and the label.

themeAccent theme used for the tooltip label.

openDelayDelay in ms before the tooltip opens.

closeDelayDelay in ms before the tooltip closes.

withArrowShow a small arrow pointing at the target.

false

arrowSizeArrow square size in px (before the internal 2× scale).

multilineAllow the label to wrap across multiple lines.

false

shadowElevation — drop shadow from the shared ladder.

disabledPrevent the tooltip from ever opening.

false

withinPortalRender the label in a portal (recommended).

true

keepMountedKeep the label node mounted while closed (hidden via display:none).

false

Playground

<Tooltip
  label="Tooltip label"
  position="top"
  offset={5}
  withArrow={false}
  arrowSize={4}
  arrowOffset={5}
  arrowRadius={0}
  multiline={false}
  disabled={false}
  withinPortal
  keepMounted={false}
  zIndex={300}
/>

Examples

Transitions

Configurable enter/exit animation via transitionProps. Pick a preset, then toggle the label to watch it animate (shared Transition engine — same presets on web and native).

Loading example…

TransitionsSource Storybook

Positions

All twelve supported placements displayed at once for a quick visual overview.

Loading example…

PositionsSource Storybook

With Arrow

Tooltip with an arrow pointing at its target; arrow size is configurable.

Loading example…

With ArrowSource Storybook

Theme

Tooltip label colors follow the active Tamagui theme.

Loading example…

ThemeSource Storybook

Disabled

Disabled tooltip — even with opened forced it never shows the label.

Loading example…

DisabledSource Storybook

Multiline

Multiline label — wraps long content instead of truncating at 320 px.

Loading example…

MultilineSource Storybook

Delays

Open and close delays add a intentional pause before the label appears or disappears.

Loading example…

DelaysSource Storybook

Controlled

Controlled open state — the parent drives visibility via React state.

Loading example…

ControlledSource Storybook

Events

Touch and focus events can trigger the tooltip in addition to (or instead of) hover.

Loading example…

EventsSource Storybook

Shadows

Optional elevation via the shadow prop — the shared ladder from xs to xl.

Loading example…

ShadowsSource Storybook

Styles

Per-slot styles targets individual parts — here the dropdown and label.

Loading example…

StylesSource Storybook

Props

Prop	Type	Default	Description
`children` required	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Single target element that accepts a ref.
`label` required	`ReactNode`	`Tooltip label`	Floating label content shown when the tooltip opens.
`animation`	`MotionPresetName \| undefined`	—	Motion preset for the label — the unified `animation` vocabulary shared with Modal/Dialog/Drawer (e.g. `"fade"`, `"pop"`, `"scale"`). Sugar over `transitionProps.transition`, which wins if both are set.
`arrowOffset`	`number \| undefined`	`5`	Arrow distance from the start/end edge when `arrowPosition="side"`.
`arrowPosition`	`ArrowPosition \| undefined`	`'side'`	Arrow alignment: centered, or pinned toward an aligned placement.
`arrowRadius`	`number \| undefined`	`0`	Corner radius of the arrow's outward corner in px.
`arrowSize`	`number \| undefined`	`4`	Arrow square size in px (before the internal 2× scale).
`closeDelay`	`number \| undefined`	`0`	Delay in ms before the tooltip closes.
`defaultOpened`	`boolean \| undefined`	—	Uncontrolled initial opened state.
`disabled` system	`boolean \| undefined`	`false`	Prevent the tooltip from ever opening.
`events`	`Partial<TooltipEvents> \| undefined`	`{ hover: true, focus: false, touch: false }`	Which interactions open the tooltip.
`inline`	`boolean \| undefined`	`false`	Position correctly around an inline/wrapping target (floating-ui `inline` middleware). Works on web and native.
`keepMounted`	`boolean \| undefined`	`false`	Keep the label node mounted while closed (hidden via display:none).
`multiline`	`boolean \| undefined`	`false`	Allow the label to wrap across multiple lines.
`offset`	`FloatingOffset \| undefined`	`5`	Main-axis gap in px between the target and the label.
`onPositionChange`	`((position: TooltipPosition) => void) \| undefined`	—	Called with the RESOLVED placement whenever it changes (e.g. on flip/shift).
`openDelay`	`number \| undefined`	—	Delay in ms before the tooltip opens.
`opened`	`boolean \| undefined`	—	Controlled opened state.
`position`	`Placement \| undefined` top · top-start · top-end · bottom · bottom-start · bottom-end · left · left-start · left-end · right · right-start · right-end	`'top'`	Preferred placement relative to the target element.
`radius` system	`string \| number \| undefined`	—
`refProp`	`string \| undefined`	`'ref'`	Prop used to pass the ref into the target child.
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` unset · xs · sm · md · lg · xl	—	Elevation — drop shadow from the shared ladder.
`styles` system	`SlotStyles<TooltipStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching styled part.
`theme` system	`ThemeName \| null \| undefined` unset · blue · red · green · yellow · pink · gray	—	Accent theme used for the tooltip label.
`transitionProps`	`OverlayTransitionConfig \| undefined`	`{ transition: 'fade', duration: 150, timingFunction: 'ease-in-out' }`	Enter/exit animation: { transition, duration, exitDuration, timingFunction }. Defaults to a 150ms fade.
`withArrow`	`boolean \| undefined`	`false`	Show a small arrow pointing at the target.
`withinPortal`	`boolean \| undefined`	`true`	Render the label in a portal (recommended).
`zIndex`	`number \| undefined`	`300`	Label `z-index`.

Style slots

Every part of Tooltip can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`arrow`	`styles={{ arrow: { … } }}`
`dropdown`	`styles={{ dropdown: { … } }}`
`label`	`styles={{ label: { … } }}`
`text`	`styles={{ text: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 495 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.