Tooltips look simple, yet building one that feels instant, reads clearly, and behaves well under keyboard, mouse, and touch takes care. In this guide you will craft a production-grade tooltip with a clean caret arrow, flexible placement, smooth motion, theming with CSS variables, and baked-in accessibility. By the end, you will have a reusable pattern you can drop into any UI.
Why The Anatomy of a Perfect Tooltip Matters
Tooltips carry microcopy that removes guesswork without bloating the interface. A solid pattern prevents overlap bugs, jittery motion, and unreadable contrast. With modern CSS you can handle placement, animation, and theming without a heavy script. You still gain progressive enhancement with a tiny sprinkle of attributes when you need them. Teams ship faster when this element is done right once and standardized.
Prerequisites
You do not need a framework for this pattern. A small amount of HTML and CSS is enough. The caret arrow uses a classic border triangle and a pseudo-element.
- Basic HTML
- CSS custom properties
- CSS pseudo-elements (::before / ::after)
Step 1: The HTML Structure
The entire component hinges on a simple anchor element for the trigger and an inner element for the tooltip. The trigger holds aria-describedby to associate the tooltip text, and the tooltip itself carries role=”tooltip”. Using data-placement lets CSS handle top or bottom positions cleanly.
<!-- HTML -->
<div class="demo">
<button class="has-tooltip" aria-describedby="tip-save">
Save
<span class="tooltip" id="tip-save" role="tooltip" data-placement="top">
Save your changes
</span>
</button>
<button class="has-tooltip" aria-describedby="tip-delete">
Delete
<span class="tooltip" id="tip-delete" role="tooltip" data-placement="bottom">
Deletes the item. This action cannot be undone.
</span>
</button>
</div>
The button gets the class has-tooltip to create a positioning context. The tooltip element sits inside the trigger for simpler focus handling and z-index stacking. The id on the tooltip and aria-describedby on the trigger link them for assistive tech.
Step 2: The Basic CSS & Styling
Start with CSS variables for theme, spacing, and motion. This gives you full control over color contrast, radius, and the shadow while keeping overrides tidy. The base styles below also set up the transform/opacity pattern that produces crisp animation without layout thrash.
/* CSS */
:root {
--tooltip-bg: #111;
--tooltip-fg: #fff;
--tooltip-radius: 8px;
--tooltip-gap: 10px;
--tooltip-shadow: 0 10px 24px rgba(0, 0, 0, 0.18);
--tooltip-font: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif;
--tooltip-max-width: 280px;
--tooltip-scale: 0.98;
--tooltip-duration: 160ms;
--tooltip-ease: cubic-bezier(0.2, 0.7, 0.2, 1);
}
*,
*::before,
*::after { box-sizing: border-box; }
body {
margin: 0;
padding: 2rem;
font-family: var(--tooltip-font);
background: #f7f7fb;
color: #222;
}
.demo {
display: flex;
gap: 2rem;
align-items: center;
flex-wrap: wrap;
}
button.has-tooltip {
position: relative; /* positioning context for the tooltip */
padding: 0.6rem 1rem;
border-radius: 10px;
border: 1px solid #d9d9e0;
background: #fff;
cursor: pointer;
font-weight: 600;
box-shadow: 0 2px 0 rgba(0, 0, 0, 0.04);
}
.tooltip {
position: absolute;
z-index: 10;
max-width: var(--tooltip-max-width);
background: var(--tooltip-bg);
color: var(--tooltip-fg);
border-radius: var(--tooltip-radius);
padding: 0.5rem 0.7rem;
box-shadow: var(--tooltip-shadow);
line-height: 1.25;
font-size: 0.9rem;
pointer-events: none; /* prevents flicker during hover */
opacity: 0;
visibility: hidden;
transition:
opacity var(--tooltip-duration) var(--tooltip-ease),
transform var(--tooltip-duration) var(--tooltip-ease),
visibility 0s linear var(--tooltip-duration);
}
/* Top placement (tooltip appears above the trigger) */
.tooltip[data-placement="top"] {
bottom: calc(100% + var(--tooltip-gap));
left: 50%;
transform-origin: 50% 100%;
transform: translate(-50%, 4px) scale(var(--tooltip-scale));
}
/* Bottom placement (tooltip appears below the trigger) */
.tooltip[data-placement="bottom"] {
top: calc(100% + var(--tooltip-gap));
left: 50%;
transform-origin: 50% 0%;
transform: translate(-50%, -4px) scale(var(--tooltip-scale));
}
/* Reveal on hover and on keyboard focus */
.has-tooltip:is(:hover, :focus-within) .tooltip {
opacity: 1;
visibility: visible;
transform: translate(-50%, 0) scale(1);
transition-delay: 0s, 0s, 0s;
}
/* Reduced motion: snap open/closed */
@media (prefers-reduced-motion: reduce) {
.tooltip {
transition: none;
}
}
Advanced Tip: Using CSS variables for colors and spacing makes theme swaps trivial. Expose a light and dark set at :root, or scope them to a container to theme a single section without touching component code.
Step 3: Building the Tooltip Bubble
The bubble is the rounded rectangle with readable contrast and a soft shadow. It should sit above or below the trigger with consistent spacing. The code below adds padding, radius, max width, and careful transform origins to make the appearing motion feel anchored to the caret.
/* CSS */
.tooltip {
background: var(--tooltip-bg);
color: var(--tooltip-fg);
border-radius: var(--tooltip-radius);
padding: 0.5rem 0.7rem;
box-shadow: var(--tooltip-shadow);
line-height: 1.25;
font-size: 0.9rem;
max-width: var(--tooltip-max-width);
word-wrap: break-word;
text-wrap: pretty;
}
/* Placement transforms for a snappy, anchored feel */
.tooltip[data-placement="top"] {
bottom: calc(100% + var(--tooltip-gap));
left: 50%;
transform-origin: 50% 100%;
transform: translate(-50%, 4px) scale(var(--tooltip-scale));
}
.tooltip[data-placement="bottom"] {
top: calc(100% + var(--tooltip-gap));
left: 50%;
transform-origin: 50% 0%;
transform: translate(-50%, -4px) scale(var(--tooltip-scale));
}
/* Show state inherited from the previous section, repeated here for clarity */
.has-tooltip:is(:hover, :focus-within) .tooltip {
opacity: 1;
visibility: visible;
transform: translate(-50%, 0) scale(1);
}
How This Works (Code Breakdown)
The tooltip uses position: absolute so it can sit relative to the button, which holds position: relative. That isolates the tooltip from unrelated layout shifts and keeps offsets simple. The bubble has a max-width to prevent long text from stretching across the viewport, and text-wrap: pretty yields tidy wrapping. The transform-origin moves to the edge closest to the caret so scaling feels attached, not floating.
Opacity and transform drive the reveal. This pair avoids layout recalculation and paints on the compositor path, so the animation feels crisp even under load. Users who prefer less motion get an instant snap because the reduce-motion media query removes the transition.
If you want a single element version with a pre-built arrow and tail, explore how to make a tooltip shape with CSS. The pattern in this article keeps the bubble and caret separate to allow per-edge placement and more control.
Step 4: Building the Caret Arrow
The caret can be drawn with a border triangle on a pseudo-element. You avoid extra markup and keep hit testing clean by disabling pointer events on the tooltip. For top placement you want a downward-pointing caret attached under the bubble. For bottom placement you want an upward-pointing caret attached above the bubble.
/* CSS */
/* Base pseudo-element: invisible by default, sized by borders */
.tooltip::after {
content: "";
position: absolute;
width: 0;
height: 0;
border-left: 6px solid transparent;
border-right: 6px solid transparent;
}
/* When the bubble sits on top, the caret points down */
.tooltip[data-placement="top"]::after {
top: 100%; /* place just below the bubble */
left: 50%;
transform: translateX(-50%);
border-top: 6px solid var(--tooltip-bg); /* triangle-down */
}
/* When the bubble sits below, the caret points up */
.tooltip[data-placement="bottom"]::after {
bottom: 100%; /* place just above the bubble */
left: 50%;
transform: translateX(-50%);
border-bottom: 6px solid var(--tooltip-bg); /* triangle-up */
}
How This Works (Code Breakdown)
The caret has zero width and height. The borders create the triangle by coloring one edge and keeping the other sides transparent. For the top placement the visible border is on the top edge, generating a downward-pointing caret that hangs from the bottom of the bubble. For the bottom placement the visible border is on the bottom edge, creating an upward-pointing caret that sits above the bubble.
If you want a refresher on drawing these arrows, see how to make a triangle down with CSS and how to make a triangle up with CSS. The caret size matches the gap and the bubble radius for a tight join, preventing a dark seam or a visible step.
The caret is centered with left: 50% and a horizontal translate. That saves you from hard-coded offsets and keeps the triangle aligned even as the bubble width changes. Placing it using top: 100% or bottom: 100% positions it just outside the rounded rectangle, so the tip points directly toward the trigger.
Advanced Techniques: Adding Animations & Hover Effects
A short scale and slide makes the tooltip feel responsive without stealing attention. Animating both opacity and transform keeps paint cheap. You can also add placement-aware offsets so top tooltips slide up while bottom tooltips slide down, which is already set in the base transforms. The snippets below add a subtle glow on the trigger to assist spatial memory and a small delay to reduce accidental flicker.
/* CSS */
/* Gentle trigger feedback */
button.has-tooltip:is(:hover, :focus-visible) {
box-shadow: 0 0 0 4px rgba(0, 112, 243, 0.15), 0 2px 0 rgba(0, 0, 0, 0.04);
border-color: #8cc5ff;
}
/* Optional: delay show to avoid flashing during flyovers; instant on focus */
.has-tooltip:hover .tooltip {
transition-delay: 90ms, 90ms, 0s;
}
.has-tooltip:focus-within .tooltip {
transition-delay: 0s, 0s, 0s;
}
/* Optional: a more pronounced entrance for dense UIs */
@keyframes tooltip-pop {
from { opacity: 0; transform: translate(-50%, var(--offset, 4px)) scale(0.98); }
to { opacity: 1; transform: translate(-50%, 0) scale(1); }
}
.tooltip[data-placement="top"] { --offset: 4px; }
.tooltip[data-placement="bottom"] { --offset: -4px; }
.has-tooltip:is(:hover, :focus-within) .tooltip.use-keyframes {
animation: tooltip-pop var(--tooltip-duration) var(--tooltip-ease) both;
}
Keyframes give you a single declaration for entrance, useful if you need a different easing curve or want to stagger multiple tooltips in a dense table. The offset custom property flips direction based on placement, so the motion always heads toward the trigger, not away from it.
Accessibility & Performance
Quality tooltips help users without becoming roadblocks. The right ARIA wiring, motion controls, and reading order make the component predictable. On the performance side, use properties that animate well and avoid layout trashing.
Accessibility
Connect the trigger and tooltip with aria-describedby on the trigger and a matching id on the tooltip. Keep role=”tooltip” on the tooltip so screen readers treat the text as advisory, not as a dialog. The CSS in this pattern shows the bubble on :hover and :focus-within, which covers mouse and keyboard. Use :focus-visible to avoid noisy focus outlines for mouse users while preserving clarity for keyboard users.
Keep tooltip content short and avoid interactive controls inside the bubble. A tooltip should explain, not become a mini menu. If you must add interaction, switch to a popover or dialog pattern. Maintain strong color contrast between var(–tooltip-bg) and var(–tooltip-fg) and test both light and dark themes.
Motion can affect comfort. The prefers-reduced-motion query swaps in instant state changes. Respect that preference for all entrance effects and any decorative trigger glow.
Performance
Transform and opacity animate on the compositor, which keeps frames smooth. The caret is a pseudo-element, so there is no extra DOM node per tooltip. Box shadows remain static during animation to avoid expensive repaints. The tooltip is absolutely positioned relative to the trigger, which prevents full-document layout during show and hide.
If you need dynamic edge detection or viewport-aware flipping, add a tiny script to toggle data-placement based on bounding boxes. The CSS stays the same, and the render work remains light because only transform and opacity change.
Tooltips That Pull Their Weight
You built a tooltip that reads well, positions cleanly above or below, and carries a crisp caret arrow without extra markup. The pattern is themeable, animates smoothly, and respects accessibility from the start.
Now you can attach this component to any control and trust it under keyboard, mouse, or touch. Extend it with left and right placements or wrap it in a utility class to standardize tooltips across your entire design system.