Primitives

Tooltip

Hover or focus hint popup with Base UI positioning and Control UI tokens.

Composition

Anatomy

<TooltipProvider>
- <Tooltip>
  - <TooltipTrigger />
  - <TooltipContent />
  </Tooltip>
</TooltipProvider>

Installation

First install and activate one skin. Core deliberately contains no visual token defaults.

The Control UI source installs this primitive from src/registry/sources/control-ui/ui/tooltip.tsx.

Registry command

npx shadcn@latest add https://control-ui.dev/r/tooltip.json

See registry manifest

Dependencies

DialogdialogPrimitive

Raw code

Primary installed source

src/registry/sources/control-ui/ui/tooltip.tsx

"use client";

import type { TooltipPopupProps, TooltipPositionerProps } from "@base-ui/react/tooltip";

import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip";

import type { ComponentProps, CSSProperties, Ref } from "react";

import type { PopupKnobStyle } from "@/components/control-ui/knob-contracts/popup-knobs";

import { cn } from "@/components/control-ui/lib/cn";

import { PopupArrowShape } from "@/components/control-ui/popup-parts";

import { controlEffectsAttribute } from "@/components/control-ui/skin";

import { useSkin } from "@/components/control-ui/skin-provider";

export function TooltipProvider({ delay = 500, ...props }: ComponentProps<typeof TooltipPrimitive.Provider>) {

return <TooltipPrimitive.Provider delay={delay} {...props} />;

}

export function Tooltip(props: ComponentProps<typeof TooltipPrimitive.Root>) {

return <TooltipPrimitive.Root {...props} />;

}

type TooltipTriggerProps = ComponentProps<typeof TooltipPrimitive.Trigger> & {

ref?: Ref<HTMLButtonElement>;

};

export function TooltipTrigger({ render, children, ref, ...props }: TooltipTriggerProps) {

return (

<TooltipPrimitive.Trigger ref={ref} render={render} {...props}>

{children}

</TooltipPrimitive.Trigger>

);

}

type TooltipContentPositionerProps = Omit<TooltipPositionerProps, keyof TooltipPopupProps>;

export type TooltipContentProps = Omit<TooltipPopupProps & Omit<TooltipContentPositionerProps, "style">, "style"> & {

style?: CSSProperties & PopupKnobStyle;

} & {

arrow?: boolean;

hidden?: boolean;

ref?: Ref<HTMLDivElement>;

};

export function TooltipContent({

className,

children,

side = "top",

sideOffset = 8,

align = "center",

alignOffset = 0,

arrowPadding = 10,

anchor,

positionMethod,

collisionBoundary,

collisionPadding,

sticky,

disableAnchorTracking,

collisionAvoidance,

arrow = true,

hidden = false,

ref,

...props

}: TooltipContentProps) {

const skin = useSkin();

if (hidden) return null;

const positionerProps: TooltipContentPositionerProps = {

side,

sideOffset,

align,

alignOffset,

arrowPadding,

anchor,

positionMethod,

collisionBoundary,

collisionPadding,

sticky,

disableAnchorTracking,

collisionAvoidance,

};

return (

<TooltipPrimitive.Portal>

<TooltipPrimitive.Positioner

data-control-ui="tooltip"

data-popup-kind="tooltip"

data-control-family="popup"

data-slot="positioner"

data-skin={skin.id}

data-effects={controlEffectsAttribute(skin.effects)}

className="z-(--z-tooltip)"

{...positionerProps}

>

<TooltipPrimitive.Popup

ref={ref}

role="tooltip"

data-control-ui="tooltip"

data-popup-kind="tooltip"

data-control-family="popup"

data-popup-part="surface"

data-slot="content"

data-arrow={arrow ? "true" : undefined}

className={cn("relative flex w-fit max-w-xs flex-col", className)}

{...props}

>

{children}

{arrow ? (

<TooltipPrimitive.Arrow

data-control-ui="tooltip"

data-control-family="popup"

data-popup-kind="tooltip"

data-slot="arrow"

className="flex"

>

<PopupArrowShape />

</TooltipPrimitive.Arrow>

) : null}

</TooltipPrimitive.Popup>

</TooltipPrimitive.Positioner>

</TooltipPrimitive.Portal>

);

}

Knobs

Typed custom properties the recipe paints with. Set one on the root — style, a utility class, or a skin — and every slot inherits it.

--cui-popup-* · 44 knobsHow the cascade resolves

--cui-popup-title-foreground<color>var(--cui-popup-foreground)

--cui-popup-title-font-size<length-percentage>var(--text-heading-3)

--cui-popup-title-font-weight<number>var(--font-weight-semibold)

--cui-popup-title-line-height<number>var(--text-heading-3--line-height)

--cui-popup-title-letter-spacing<length>-0.025em

--cui-popup-description-foreground<color>var(--muted-foreground)

--cui-popup-close-inset<length-percentage>calc(var(--spacing) * 3)

--cui-popup-item-inset<length-percentage>calc(var(--spacing) * 8)

--cui-popup-label-padding-block<length-percentage>var(--cui-popup-item-padding-block)

--cui-popup-label-padding-inline<length-percentage>var(--cui-popup-item-padding-inline)

--cui-popup-label-font-size<length-percentage>var(--text-micro)

--cui-popup-label-font-weight<number>var(--font-weight-medium)

--cui-popup-label-letter-spacing<length>0.08em

--cui-popup-label-text-transformnone | uppercase | lowercase | capitalizeuppercase

--cui-popup-separator-inset<length-percentage>calc(var(--popover-padding) * -1)

--cui-popup-shortcut-font-size<length-percentage>var(--text-body)

--cui-popup-shortcut-letter-spacing<length>0.02em

--cui-popup-status-success-foreground<color>var(--success-text)

--cui-popup-status-warning-foreground<color>var(--warning-text)

--cui-popup-status-info-foreground<color>var(--info-text)

--cui-popup-status-error-foreground<color>var(--destructive)

--cui-popup-radius<length-percentage>var(--radius-popover)

--cui-popup-background<color>var(--popover)

--cui-popup-foreground<color>var(--popover-foreground)

--cui-popup-border-color<color>var(--control-rim)

--cui-popup-border-width<length>var(--control-rim-width)

--cui-popup-shadow*var(--shadow-pop)

--cui-popup-backdrop-filter*blur(var(--backdrop-blur-popover))

--cui-popup-backdrop-background<color>oklch(from var(--foreground) l c h / var(--overlay-opacity))

--cui-popup-backdrop-blur<length>var(--backdrop-blur-overlay)

--cui-popup-item-radius<length-percentage>var(--radius-popup-item-fit)

--cui-popup-item-font-size<length-percentage>var(--text-body)

--cui-popup-item-icon-size<length-percentage>1rem

--cui-popup-item-padding-block<length-percentage>calc(var(--spacing) * 1)

--cui-popup-item-padding-inline<length-percentage>calc(var(--padding-x) * 0.5)

--cui-popup-item-min-height<length-percentage>max(var(--target-min), var(--control-h-xs))

--cui-popup-item-highlight-shadow*inset 0 0 0 1px oklch(from var(--foreground) l c h / 0.35)

--cui-popup-item-foreground<color>var(--foreground)

--cui-popup-item-highlight-background<color>var(--hover-fill)

--cui-popup-item-highlight-foreground<color>var(--cui-popup-item-foreground)

--cui-popup-item-highlight-muted-foreground<color>var(--muted-foreground)

--cui-popup-item-disabled-opacity<number>var(--disabled-opacity)

--cui-popup-separator-color<color>var(--border)

--cui-popup-shortcut-foreground<color>var(--muted-foreground)