What is a tooltip?
A tooltip is a small message that pops up when you point at something on a page. It might explain where a link goes, what an icon button does, or give a little extra detail about a word.
Have you ever wanted to create tooltips with nothing but CSS? In this tutorial we'll do exactly that, with no JavaScript and no images, just a little HTML and pure CSS.
Here's what we're building. Hover over the link, or press Tab on your keyboard until it's highlighted:
We'll build it in four steps, then look at placing the tooltip on different sides and how to make sure everyone can use it.
Step 1: the HTML
The original version of this tutorial put the tooltip text inside the link itself. That works visually, but it means a screen reader reads the tooltip as part of the link's name. Here's a better structure:
<span class="tooltip">
<a href="/css-properties/" aria-describedby="tip-1">CSS Properties</a>
<span class="tooltip__text" role="tooltip" id="tip-1">Browse every CSS property</span>
</span>
There are three parts:
- The wrapper (
.tooltip) holds everything and acts as the anchor point. - The trigger is the link that visitors point at or tab to.
- The tooltip text (
.tooltip__text) is the message itself.
Linking them for screen readers
A screen reader is software that reads pages aloud for people with low vision. Two attributes help it understand the tooltip:
role="tooltip"labels the span as a tooltip.aria-describedby="tip-1"on the link points to the tooltip'sid. The screen reader then reads the link's name followed by the tooltip as a description.
Tip: every id on a page must be unique, so give each tooltip its own, such as tip-1, tip-2 and so on.
Step 2: the tooltip box
First, the wrapper. Giving it position: relative makes it the reference point for positioning the tooltip:
.tooltip {
position: relative;
display: inline-block;
}
display: inline-block keeps the wrapper flowing inline with your text, like a normal word, while still acting as a box for positioning.
Now the tooltip itself. It starts hidden and sits centred above the link:
.tooltip__text {
position: absolute;
bottom: calc(100% + 10px);
left: 50%;
transform: translateX(-50%);
width: max-content;
max-width: 220px;
padding: 6px 10px;
border-radius: 6px;
background: #111827;
color: #ffffff;
font-size: 14px;
line-height: 1.4;
text-align: center;
opacity: 0;
visibility: hidden;
transition: opacity 0.2s ease, visibility 0.2s ease;
z-index: 10;
}
Line by line
| Line | What it does |
|---|---|
position: absolute; | Lifts the tooltip out of the normal flow so it can float over other content |
bottom: calc(100% + 10px); | Places the tooltip's bottom edge 10px above the top of the link, leaving room for the arrow |
left: 50%; | Moves the tooltip's left edge to the middle of the link |
transform: translateX(-50%); | Shifts it back by half its own width, so it's perfectly centred |
width: max-content; | Makes the box only as wide as its text needs |
max-width: 220px; | Wraps longer messages onto several lines instead of one very long line |
padding, border-radius | Breathing room around the text, and softly rounded corners |
background, color | Near-black box with white text, for strong contrast |
opacity: 0; and visibility: hidden; | Hide the tooltip until it's needed |
transition | Fades the tooltip in and out smoothly instead of snapping |
z-index: 10; | Keeps the tooltip on top of nearby content |
What changed since the old version? The original used a fixed width: 140px with margin-left: -76px to centre it. If you changed the width, you had to recalculate the margin by hand. translateX(-50%) centres the tooltip whatever its width, so the box can simply fit its text.
Why both opacity and visibility?
visibility can't fade; it simply switches on or off. opacity can fade, but an element with zero opacity is still there, just invisible, and can still be hovered. Using both gives us a smooth fade and a tooltip that's properly hidden when it's not showing.
Step 3: the arrow
A small arrow pointing at the link makes it clear what the tooltip belongs to. We'll draw it with the ::after pseudo-element, which adds an extra box to an element using CSS alone.
The border triangle trick
CSS has no triangle shape, but there's a clever trick. Where two borders meet, the browser joins them with a diagonal line. Give a box zero width and height but thick borders, and each border becomes a triangle:
Make every border transparent except the top one, and you're left with a downward-pointing triangle. That's our arrow:
.tooltip__text::after {
content: "";
position: absolute;
top: 100%;
left: 50%;
transform: translateX(-50%);
border: 6px solid transparent;
border-top-color: #111827;
}
content: ""is required, or the pseudo-element won't appear at all.top: 100%places the arrow just below the tooltip box.left: 50%andtranslateX(-50%)centre it, the same way we centred the box.border: 6px solid transparentsets up all four borders, thenborder-top-colorcolours just the top one to match the tooltip.
Tip: the arrow's size is set by the border width. Change 6px to 8px for a bigger arrow, and remember to increase the 10px gap from step 2 to match.
Step 4: showing the tooltip
Finally, we reveal the tooltip when the wrapper is hovered or when the link has keyboard focus:
.tooltip:hover .tooltip__text,
.tooltip:focus-within .tooltip__text {
opacity: 1;
visibility: visible;
}
:hover is a pseudo-class that matches while the mouse pointer is over an element. :focus-within matches when anything inside the element has focus, which happens when a keyboard user tabs to the link.
The original tutorial only used :hover, so people who navigate with a keyboard never saw the tooltip. Adding :focus-within fixes that with one extra line.
Respecting reduced motion
Some people find movement on screen uncomfortable and turn on a "reduce motion" setting on their device. A media query lets you switch the fade off for them:
@media (prefers-reduced-motion: reduce) {
.tooltip__text {
transition: none;
}
}
Different positions
Above the link is the most common spot, but sometimes there isn't room, for example at the very top of a page. Modifier classes let you place the tooltip on any side. Here's the version for below:
.tooltip--bottom .tooltip__text {
bottom: auto;
top: calc(100% + 10px);
}
.tooltip--bottom .tooltip__text::after {
top: auto;
bottom: 100%;
border-top-color: transparent;
border-bottom-color: #111827;
}
And for the right-hand side, the tooltip is centred vertically instead of horizontally:
.tooltip--right .tooltip__text {
bottom: auto;
top: 50%;
left: calc(100% + 10px);
transform: translateY(-50%);
}
.tooltip--right .tooltip__text::after {
top: 50%;
left: auto;
right: 100%;
transform: translateY(-50%);
border-top-color: transparent;
border-right-color: #111827;
}
The left-hand version mirrors this: use right instead of left, and colour the arrow's left border. Add the modifier next to the main class, as in <span class="tooltip tooltip--bottom">.
Accessibility and limitations
Pure CSS tooltips are great for small hints, but they have limits worth knowing before you rely on them.
Touch screens have no hover
On phones and tablets there's no mouse pointer to hover with. Tapping a link usually just follows it, so a visitor on a phone may never see your tooltip. For that reason:
Key rule: never put essential information only in a tooltip. Use tooltips for helpful extras, and keep anything people genuinely need visible on the page.
Hover only works on focusable triggers
For keyboard users to reach a tooltip, the trigger must be something they can tab to, such as a link or a button. A tooltip on a plain word or icon in a <span> can only be seen with a mouse.
Escape to close
Accessibility guidelines (WCAG) say content that appears on hover or focus should be dismissible without moving the pointer, usually with the Escape key. CSS can't listen for key presses, so if you need to meet this fully, add a few lines of JavaScript that hide the tooltip when Escape is pressed.
What about the title attribute?
HTML's built-in title attribute shows a plain browser tooltip with no CSS at all: <a href="#" title="More info">. It's quick, but you can't style it, it appears after a delay, and it's not shown to keyboard or touch users. A CSS tooltip gives you far more control.
Coming soon to CSS
Newer browser features such as the Popover API and CSS anchor positioning are designed to make tooltips smarter, for example flipping automatically to the other side when there's no room. They're not yet supported in every browser, so the technique in this tutorial remains the reliable choice for now.
The complete code
Here's all the CSS together, including the bottom and right positions:
.tooltip {
position: relative;
display: inline-block;
}
.tooltip__text {
position: absolute;
bottom: calc(100% + 10px);
left: 50%;
transform: translateX(-50%);
width: max-content;
max-width: 220px;
padding: 6px 10px;
border-radius: 6px;
background: #111827;
color: #ffffff;
font-size: 14px;
line-height: 1.4;
text-align: center;
opacity: 0;
visibility: hidden;
transition: opacity 0.2s ease, visibility 0.2s ease;
z-index: 10;
}
.tooltip__text::after {
content: "";
position: absolute;
top: 100%;
left: 50%;
transform: translateX(-50%);
border: 6px solid transparent;
border-top-color: #111827;
}
.tooltip:hover .tooltip__text,
.tooltip:focus-within .tooltip__text {
opacity: 1;
visibility: visible;
}
/* Bottom position */
.tooltip--bottom .tooltip__text { bottom: auto; top: calc(100% + 10px); }
.tooltip--bottom .tooltip__text::after {
top: auto; bottom: 100%;
border-top-color: transparent; border-bottom-color: #111827;
}
/* Right position */
.tooltip--right .tooltip__text {
bottom: auto; top: 50%; left: calc(100% + 10px); transform: translateY(-50%);
}
.tooltip--right .tooltip__text::after {
top: 50%; left: auto; right: 100%; transform: translateY(-50%);
border-top-color: transparent; border-right-color: #111827;
}
@media (prefers-reduced-motion: reduce) {
.tooltip__text { transition: none; }
}
And the HTML:
<span class="tooltip">
<a href="#" aria-describedby="tip-1">Hover over me!</a>
<span class="tooltip__text" role="tooltip" id="tip-1">Pure CSS tooltips</span>
</span>
<span class="tooltip tooltip--bottom">
<a href="#" aria-describedby="tip-2">I show below</a>
<span class="tooltip__text" role="tooltip" id="tip-2">A tooltip underneath</span>
</span>
Wrapping up
With a wrapper, one hidden box, a border-trick arrow and a hover rule, you have tooltips that fade in smoothly, work with the keyboard and sit on any side. Try changing the colours, the arrow size or the maximum width to match your own site.