Components

Tooltip

A floating label component for supplementary information, composed of a content bubble and directional arrow. Supports multiple colors, visual styles, and sizes through the recipe system.

Overview

The Tooltip is a floating label element used for supplementary context shown on hover or focus. It is composed of two recipe parts: useTooltipRecipe() for the content bubble and useTooltipArrowRecipe() for the directional arrow. Each composable creates a fully configured recipe with color and variant options — plus compound variants that handle the color-variant combinations automatically. The content recipe adds a size axis for font size and padding control, while the arrow recipe uses a CSS variable for dimension control.

The Tooltip recipes integrate directly with the default design tokens preset and generate type-safe utility classes at build time with zero runtime CSS.

Why use the Tooltip recipe?

The Tooltip recipe helps you:

  • Ship faster with sensible defaults: Get 3 colors, 3 visual styles, and 3 sizes out of the box with a pair of composable calls.
  • Compose coordinated parts: Two recipes (content and arrow) share the same color and variant axes, so your tooltips stay internally consistent.
  • Maintain consistency: Compound variants ensure every color-variant combination follows the same design rules, including dark mode overrides.
  • Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
  • Stay type-safe: Full TypeScript support means your editor catches invalid color, variant, or size values at compile time.
  • Integrate with your tokens: Every value references the design tokens preset, so theme changes propagate automatically.

Usage

Register the recipes

Add the Tooltip recipes to a local Styleframe instance. The global styleframe.config.ts provides design tokens and utilities, while the component-level file registers the recipes themselves:

src/components/tooltip.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import {
    useTooltipRecipe,
    useTooltipArrowRecipe,
} from '@styleframe/theme';

const s = styleframe();

const tooltip = useTooltipRecipe(s);
const tooltipArrow = useTooltipArrowRecipe(s);

export default s;

Build the component

Import the tooltip and tooltipArrow runtime functions from the virtual module and pass variant props to compute class names:

src/components/Tooltip.tsx
import { tooltip, tooltipArrow, type TooltipProps } from "virtual:styleframe";

interface TooltipComponentProps extends TooltipProps {
    label?: string;
    children?: React.ReactNode;
}

export function Tooltip({
    color = "dark",
    variant = "solid",
    size = "md",
    label,
    children,
}: TooltipComponentProps) {
    return (
        <div className="tooltip-wrapper">
            <span
                className={tooltip({ color, variant, size })}
                role="tooltip"
            >
                {children ?? label}
            </span>
            <span className={`${tooltipArrow({ color, variant })} tooltip-arrow-position`} />
        </div>
    );
}

See it in action

Colors

The Tooltip recipe includes 3 color variants: light, dark, and neutral. Like the Card recipe, the Tooltip uses neutral-spectrum colors designed for supplementary surfaces rather than status communication. Each color is combined with every visual style variant through compound variants, so you get consistent, predictable styling across all combinations — including dark mode overrides.

The default color is dark, which provides strong contrast against most page backgrounds and is the most common tooltip style across interfaces.

Color Reference

ColorTokenUse Case
light@color.white / @color.gray-*Light tooltips, stays light in dark mode
dark@color.gray-900Dark tooltips, stays dark in light mode (default)
neutralAdaptive (light ↔ dark)Adapts to the current color scheme
Pro tip: Use dark as your default tooltip color. Dark tooltips provide strong contrast against most page backgrounds, making the supplementary text easy to read at a glance.

Variants

Three visual style variants control how the tooltip is rendered. Each variant is combined with the selected color through compound variants, so you always get the correct background, text, and border colors for your chosen color.

Solid

Filled background with a subtle border. The most prominent style, ideal for standard tooltips that need clear visibility.

Soft

Light tinted background with no visible border. A gentler style that works well for tooltips in dense layouts where a bordered tooltip would feel heavy.

Subtle

Light tinted background with a matching border. Combines the softness of the soft variant with added visual definition from a border.

Sizes

Three size variants from sm to lg control the font size, padding, and border radius of the tooltip content.

Size Reference

SizeFont SizePadding (V / H)Border Radius
sm@font-size.xs@0.25 / @0.5@border-radius.sm
md@font-size.sm@0.375 / @0.625@border-radius.md
lg@font-size.md@0.5 / @0.75@border-radius.md
Good to know: The size prop only applies to useTooltipRecipe(). The arrow recipe (useTooltipArrowRecipe()) does not have a size variant — its dimensions are controlled by the @tooltip.arrow.size CSS variable (default: 5px).

Anatomy

The Tooltip recipe is composed of two independent recipes that work together to form a complete tooltip:

PartRecipeRole
ContentuseTooltipRecipe()The tooltip bubble with background, border, text styling, and shadow. On an element with the popover attribute it opens in the top layer beside its trigger
ArrowuseTooltipArrowRecipe()Directional indicator using CSS border-triangle technique, turned by placement

The color and variant props should be passed consistently to both recipes so that the arrow colours match the tooltip bubble. Pass the same placement to both too, so the arrow points back at the trigger. The arrow recipe registers a @tooltip.arrow.size CSS variable (default 5px) that controls the arrow dimensions.

<!-- Both parts working together -->
<div class="tooltip-wrapper">
    <span class="tooltip(...)" role="tooltip">Tooltip text</span>
    <span class="tooltipArrow(...) tooltip-arrow-position" />
</div>
Pro tip: Outside the top layer, the arrow's position isn't part of the recipe, so place it beside the content with your own CSS, like the tooltip-arrow-position class above. Inside a top-layer tooltip, put the arrow inside the content and the recipe places it for you.

Accessibility

The Tooltip recipe follows the Open Components Tooltip standard for everything a stylesheet decides. Your component still wires up the behaviour, which the list at the end of this section walks you through.

Top layer and placement

Give the content the popover attribute and the recipe opens it in the top layer, so no overflow: hidden or z-index around its trigger can clip or cover it. On .tooltip[popover] it sets position: fixed, inset: auto and the @tooltip.offset gap (@spacing.xs by default) as its margin, and hides it while it's closed. The @z-index.tooltip layer stays on every tooltip, and every other use keeps its own positioning, so tooltips you position yourself stay where you put them. Their width changes, since every tooltip now wraps at 32ch rather than 240px, as the next section explains.

The placement axis says which side of its trigger the tooltip opens on: top (the default), bottom, start or end. It sets position-area, and position-try-fallbacks: flip-block, flip-inline flips it to the other side when there's no room. The start and end placements follow the tooltip's own direction, so they swap sides in right-to-left languages.

Point the tooltip at its trigger with anchor-name on the trigger and position-anchor on the tooltip. Both take the same dashed name, here --save, set through the save-trigger and save-tooltip classes:

src/components/tooltip.styleframe.ts
import { styleframe } from 'virtual:styleframe';

const s = styleframe();
const { selector } = s;

selector('.save-trigger', {
    anchorName: '--save',
});

selector('.save-tooltip', {
    positionAnchor: '--save',
});

export default s;

Inside a top-layer tooltip, the arrow sits on the edge that faces the trigger, centred on it. CSS can't tell which side a fallback chose, so if your tooltip flips, update the arrow's placement from a script to the side it opened on.

Wrapping and motion

The content is never wider than 32ch, so long text wraps at about 32 characters however large it gets, and overflow-wrap: anywhere breaks a long word rather than letting it spill out. A top-layer tooltip fades and grows in over @duration.fast, from @starting-style. With prefers-reduced-motion: reduce, it only fades in, without growing.

Contrast and forced colours

  • Text. Every color and variant, light and dark included, keeps its text at 4.5:1 or more against its fill in both themes, which tooltipContrast.test.ts checks from the tokens.
  • Forced colours. Forced colours mode drops the fill and the shadow, so under &:forced-colors the content takes Canvas and CanvasText, and its border, transparent in the soft variant, marks its edge in CanvasText. The border-drawn arrow is hidden there, since the system colours would turn it into a block.

The tooltip never takes focus, so it draws no focus ring of its own. Its trigger shows focus the way it does everywhere else, in color.focus.

Behaviour your component adds

  • Use role="tooltip" and aria-describedby. The tooltip element needs role="tooltip" and a unique id. The trigger element references it with aria-describedby.
<!-- Correct: trigger linked to tooltip via aria-describedby -->
<button aria-describedby="tooltip-1">Hover me</button>
<div role="tooltip" id="tooltip-1" class="...">Helpful description</div>
  • Show on focus, not just hover. Tooltips must be accessible via keyboard. Show the tooltip when the trigger receives focus, and hide it on blur.
<!-- Correct: tooltip shown on both hover and focus -->
<button
    aria-describedby="tooltip-2"
    onfocus="showTooltip()"
    onblur="hideTooltip()"
    onmouseenter="showTooltip()"
    onmouseleave="hideTooltip()">
    Hover or focus me
</button>
  • Allow dismissal with Escape. Users should be able to dismiss the tooltip by pressing Escape without moving focus (WCAG 1.4.13).
  • Keep content concise. Tooltips are for supplementary information, not essential content. If the information is critical, use an inline label or a callout instead.
  • Verify contrast ratios. The solid variant with dark color places light text on a dark background. Default tokens meet WCAG AA 4.5:1 contrast. If you override colors, verify with the WebAIM Contrast Checker.

Customization

Overriding Defaults

Each tooltip composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults, so you only need to specify the properties you want to change:

src/components/tooltip.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import {
    useTooltipRecipe,
    useTooltipArrowRecipe,
} from '@styleframe/theme';

const s = styleframe();

const tooltip = useTooltipRecipe(s, {
    base: {
        borderRadius: '@border-radius.lg',
        maxWidth: '320px',
    },
    defaultVariants: {
        color: 'neutral',
        variant: 'subtle',
        size: 'lg',
    },
});

const tooltipArrow = useTooltipArrowRecipe(s, {
    defaultVariants: {
        color: 'neutral',
        variant: 'subtle',
    },
});

export default s;

Filtering Variants

If you only need a subset of the available variants, use the filter option to limit which values are generated. This reduces the output CSS and keeps your component API focused:

src/components/tooltip.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import { useTooltipRecipe, useTooltipArrowRecipe } from '@styleframe/theme';

const s = styleframe();

// Only generate dark color with solid style
const tooltip = useTooltipRecipe(s, {
    filter: {
        color: ['dark'],
        variant: ['solid'],
    },
});

const tooltipArrow = useTooltipArrowRecipe(s, {
    filter: {
        color: ['dark'],
        variant: ['solid'],
    },
});

export default s;
Good to know: Filtering also removes compound variants and adjusts default variants that reference filtered-out values, so your recipe stays consistent.

API Reference

useTooltipRecipe(s, options?)

Creates the tooltip content bubble recipe with background, border, text styling, padding, and shadow. Registers the @tooltip.offset CSS variable (default: @spacing.xs) and the top-layer selectors for .tooltip[popover].

Parameters:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles for the tooltip content
options.variantsVariantsCustom variant definitions for the recipe
options.defaultVariantsRecord<keyof Variants, string>Default variant values for the recipe
options.compoundVariantsCompoundVariant[]Custom compound variant definitions for the recipe
options.filterRecord<string, string[]>Limit which variant values are generated

Variants:

VariantOptionsDefault
colorlight, dark, neutraldark
variantsolid, soft, subtlesolid
sizesm, md, lgmd
placementtop, bottom, start, endtop

useTooltipArrowRecipe(s, options?)

Creates the tooltip arrow recipe using a CSS border-triangle technique with a pseudo-element for the inner fill. Registers the @tooltip.arrow.size CSS variable (default: 5px), and the selectors that place it on the edge of a top-layer tooltip.

Parameters:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles for the tooltip arrow
options.variantsVariantsCustom variant definitions for the recipe
options.defaultVariantsRecord<keyof Variants, string>Default variant values for the recipe
options.compoundVariantsCompoundVariant[]Custom compound variant definitions for the recipe
options.filterRecord<string, string[]>Limit which variant values are generated

Variants:

VariantOptionsDefault
colorlight, dark, neutraldark
variantsolid, soft, subtlesolid
placementtop, bottom, start, endtop

Learn more about recipes →

Best Practices

  • Pass color, variant and placement consistently: Both the content and arrow recipes need the same values, so the arrow colours match the tooltip bubble and the arrow points at the trigger.
  • Use dark for general-purpose tooltips: Dark tooltips provide strong contrast against most page backgrounds, making them the most readable default.
  • Keep tooltip text short: Tooltips should provide brief supplementary context, not paragraphs of content. The default maxWidth of 32ch keeps lines to about 32 characters.
  • Never put essential information in tooltips: Tooltips are hidden by default and inaccessible on touch devices. Critical information should be visible inline.
  • Use the popover attribute for placement: On a [popover] element the recipe places and flips the tooltip with CSS anchor positioning. Browsers without it need a script, like Floating UI, to place the tooltip and set the arrow's placement.
  • Filter what you don't need: If your application only uses dark tooltips, pass a filter option to reduce generated CSS.
  • Override defaults at the recipe level: Set your most common variant combination as defaultVariants so component consumers write less code.

FAQ