Published on

Mastering the Hover: A Step-by-Step Guide to Building a Custom Tooltip

Authors

'Mastering the Hover: A Step-by-Step Guide to Building a Custom Tooltip'

Dive deep into creating a responsive and accessible tooltip from scratch. This comprehensive guide takes you from a simple CSS-only solution to a robust JavaScript-powered component, covering positioning, edge detection, and ARIA best practices.

Table of Contents

Tooltips. They are the unsung heroes of clean user interfaces. These small pop-up boxes provide context, hints, and extra information right when you need it, without cluttering the screen. From explaining a cryptic icon button to providing validation errors, a well-designed tooltip is an essential part of a great user experience.

But have you ever wondered what it takes to build one from scratch? It might seem simple, but creating a tooltip that is robust, responsive, and—most importantly—accessible can be a surprisingly deep and rewarding challenge.

In this comprehensive guide, we'll embark on a journey to build the perfect tooltip. We'll start with a simple, elegant solution using only HTML and CSS. Then, we'll progressively enhance it with JavaScript to handle complex positioning, dynamic content, and critical accessibility features. By the end, you won't just have a snippet to copy and paste; you'll have a deep understanding of the principles behind building high-quality UI components.

Ready? Let's get building.

Section 1: The Foundation - Structuring the Tooltip with HTML

Every great structure starts with a solid foundation. For our tooltip, this means clean and semantic HTML. We want a structure that is easy to understand, style, and manipulate with JavaScript later on.

Let's start with a trigger element (the thing you'll hover over) and the tooltip's content. A common and effective pattern is to wrap the trigger element in a container and place the tooltip text inside a <span> or <div>.

A modern and highly recommended best practice is to store the tooltip's content within a data-* attribute. This keeps your content neatly associated with its trigger, making the HTML cleaner and the JavaScript logic more straightforward.

Here's our foundational HTML structure:

<div class="tooltip-container">
  <button class="tooltip-trigger">Hover Over Me</button>
  <span class="tooltip-text">This is the tooltip! 👋</span>
</div>

<!-- A more flexible approach using data-attributes -->
<p>
  You can also have tooltips on 
  <span class="tooltip-container">
    <span class="tooltip-trigger" tabindex="0" data-tooltip="This is another tooltip!">
      inline text
    </span>
  </span>.
</p>

Let's break this down:

  • .tooltip-container: This element is crucial for positioning. We'll set its position to relative, which will serve as the anchor for our absolutely positioned tooltip.
  • .tooltip-trigger: This is the element the user interacts with. It can be a button, a span, an icon—anything you want. We've added tabindex="0" to the inline text example to ensure that non-interactive elements like <span> can receive keyboard focus, which is a key first step towards accessibility.
  • .tooltip-text / data-tooltip: The first example shows the tooltip text directly in the HTML. The second, more scalable approach, uses a data-tooltip attribute. We'll focus on the data-attribute method as we move to JavaScript, as it's far more flexible.

Section 2: The Visuals - Styling with a Pure CSS Approach

With our HTML in place, we can now bring the tooltip to life with CSS. For a simple tooltip that appears directly above the trigger, CSS is surprisingly powerful. The core technique relies on a combination of position, visibility, and the :hover pseudo-class.

First, let's style the container and the tooltip text itself.

/* The container needs to be relative to anchor the tooltip */
.tooltip-container {
  position: relative;
  display: inline-block; /* Or block, depending on your layout */
}

/* The tooltip text - hidden by default */
.tooltip-text {
  visibility: hidden;
  opacity: 0;
  
  /* Basic styling */
  background-color: #333;
  color: #fff;
  text-align: center;
  border-radius: 6px;
  padding: 8px 12px;
  font-size: 14px;
  
  /* Positioning */
  position: absolute;
  z-index: 1;
  bottom: 125%; /* Position it above the trigger */
  left: 50%;
  transform: translateX(-50%);

  /* Smooth transition for fading in */
  transition: opacity 0.3s ease, visibility 0.3s ease;
}

Let's dissect that positioning magic:

  1. position: absolute: This takes the tooltip out of the normal document flow and allows us to position it relative to its nearest positioned ancestor, which is our .tooltip-container with position: relative.
  2. bottom: 125%: This places the bottom of the tooltip 125% of the container's height above the container. The extra 25% creates a small gap.
  3. left: 50% and transform: translateX(-50%): This is a classic CSS centering trick. left: 50% moves the left edge of the tooltip to the horizontal center of the container. Then, transform: translateX(-50%) shifts the tooltip back to the left by 50% of its own width, perfectly centering it.
  4. visibility: hidden & opacity: 0: We hide the tooltip by default. We use both properties because visibility: hidden removes the element from being interactive (you can't accidentally select its text), while opacity: 0 allows us to apply a smooth transition.

Now for the reveal! We use the :hover pseudo-class on the container to show the tooltip.

/* Show the tooltip on hover */
.tooltip-container:hover .tooltip-text {
  visibility: visible;
  opacity: 1;
}

Simple as that! When you hover over the .tooltip-container, the .tooltip-text inside it becomes visible with a nice fade effect.

Adding the Pointy Arrow

A tooltip isn't complete without that little triangular arrow pointing to its trigger element. We can create this with a clever CSS trick using a pseudo-element (::after) and borders.

/* Add the arrow using a pseudo-element */
.tooltip-text::after {
  content: "";
  position: absolute;
  top: 100%; /* Position it at the bottom of the tooltip */
  left: 50%;
  margin-left: -5px; /* Center the arrow */
  border-width: 5px;
  border-style: solid;
  border-color: #333 transparent transparent transparent;
}

How does this work? Imagine a 10px by 10px box (border-width: 5px on all sides). We then make three of its borders transparent. The only visible border is the top one (border-color: #333 transparent ...), which forms a triangle pointing downwards. We then position this pseudo-element at the bottom of the tooltip (top: 100%) and center it, creating the perfect arrow.

Section 3: The Limits of a Pure CSS Solution

The CSS-only approach is fantastic for simple cases. It's lightweight, performant, and doesn't require any JavaScript. However, it has some significant limitations that you'll quickly run into in a real-world application:

  1. Edge Detection: What happens if your tooltip trigger is near the right or left edge of the browser window? The tooltip will get cut off, creating a broken and frustrating user experience. CSS has no way of knowing the viewport's dimensions to reposition the tooltip dynamically.

  2. Dynamic Content: If your tooltip's text is very long, it might wrap and become too wide, potentially overflowing the screen. The CSS centering trick works well, but it can't adapt to content that dramatically changes the tooltip's size.

  3. Accessibility: This is the most critical drawback. The :hover pseudo-class only works for mouse users. Keyboard-only users who navigate with the Tab key, and users on touch devices, will never be able to trigger the tooltip. A truly inclusive web requires us to do better.

To overcome these challenges, we need to bring in the power and flexibility of JavaScript.

Section 4: Enhancing with JavaScript - The Dynamic & Accessible Tooltip

Let's refactor our tooltip to be created and managed by JavaScript. This will give us the control we need to solve the problems of positioning and accessibility.

Our goal is to create a script that:

  • Finds all elements that should have a tooltip.
  • Listens for mouseover and focus events to show the tooltip.
  • Listens for mouseout and blur events to hide it.
  • Creates the tooltip element dynamically in memory.
  • Calculates the perfect position, avoiding screen edges.
  • Appends the tooltip to the <body> for maximum positioning freedom.

Let's get to the code. We'll start by selecting our trigger elements and setting up the event listeners.

// main.js
document.addEventListener('DOMContentLoaded', () => {
  const triggers = document.querySelectorAll([data-tooltip]);
  let tooltipElement = null; // To hold the single tooltip instance

  function showTooltip(event) {
    const trigger = event.target;
    const tooltipText = trigger.getAttribute('data-tooltip');

    if (!tooltipText) return;

    // Create the tooltip element if it doesn't exist
    if (!tooltipElement) {
      tooltipElement = document.createElement('div');
      tooltipElement.className = 'tooltip-js';
      document.body.appendChild(tooltipElement);
    }

    // Set content and show
    tooltipElement.textContent = tooltipText;
    tooltipElement.style.display = 'block';

    // Position the tooltip
    positionTooltip(trigger);
  }

  function hideTooltip() {
    if (tooltipElement) {
      tooltipElement.style.display = 'none';
    }
  }

  triggers.forEach(trigger => {
    trigger.addEventListener('mouseover', showTooltip);
    trigger.addEventListener('focus', showTooltip);
    trigger.addEventListener('mouseout', hideTooltip);
    trigger.addEventListener('blur', hideTooltip);
  });

  // We'll define positionTooltip next
});

Key Improvements Here:

  • We use [data-tooltip] as our selector, focusing on our flexible data attribute approach.
  • We create a single tooltip element (tooltipElement) and reuse it for all triggers. This is more memory-efficient than creating a new one every time.
  • We append the tooltip to document.body. This is a professional technique that prevents the tooltip from being clipped by any parent containers with overflow: hidden and simplifies z-index management.
  • We're listening for both mouse (mouseover/mouseout) and keyboard (focus/blur) events right from the start.

The Core Logic: Positioning with JavaScript

Now for the most important part: the positionTooltip function. This function will calculate where to place the tooltip, and it's where JavaScript truly shines.

function positionTooltip(trigger) {
  const triggerRect = trigger.getBoundingClientRect();
  const tooltipRect = tooltipElement.getBoundingClientRect();
  const spacing = 10; // The gap between the trigger and the tooltip

  // Default position: above the trigger
  let top = triggerRect.top - tooltipRect.height - spacing;
  let left = triggerRect.left + (triggerRect.width / 2) - (tooltipRect.width / 2);

  // --- Edge Detection Logic ---

  // Check if it overflows on the left
  if (left < 0) {
    left = spacing;
  }

  // Check if it overflows on the right
  if (left + tooltipRect.width > window.innerWidth) {
    left = window.innerWidth - tooltipRect.width - spacing;
  }

  // Check if it overflows on the top (and reposition to the bottom)
  if (top < 0) {
    top = triggerRect.bottom + spacing;
    // We would also need to update the arrow's position here (e.g., by adding a class)
  }

  tooltipElement.style.left = `${left + window.scrollX}px`;
  tooltipElement.style.top = `${top + window.scrollY}px`;
}

Let's break down this critical function:

  1. getBoundingClientRect(): This powerful method returns an object with the size and position of an element relative to the viewport. It's the key to all our calculations.
  2. Initial Calculation: We calculate the ideal top and left positions to center the tooltip above the trigger, just like we did in CSS, but using dynamic width and height values.
  3. Edge Detection: This is the magic. We check if the calculated left is less than 0 (off the left edge) or if left + width is greater than the window.innerWidth (off the right edge). If an overflow is detected, we simply adjust the left value to bring the tooltip back into view.
  4. Top Overflow: We even check if there's enough space at the top. If not, we flip the tooltip to appear below the trigger element.
  5. Handling Scroll: getBoundingClientRect is relative to the viewport, not the document. If the page is scrolled, we must add window.scrollX and window.scrollY to our final coordinates to position the tooltip correctly within the entire page.

Don't forget to add some CSS for our new JS-powered tooltip!

.tooltip-js {
  /* Start with base styles */
  position: absolute;
  display: none; /* Controlled by JS */
  background-color: #333;
  color: #fff;
  padding: 8px 12px;
  border-radius: 6px;
  font-size: 14px;
  z-index: 1000;
  max-width: 300px; /* Prevent it from getting too wide */
}

/* We can still use pseudo-elements for the arrow! */
.tooltip-js::after {
  /* ... same arrow styles as before ... */
}

Section 5: A Deeper Dive into Accessibility (ARIA)

We've made our tooltip keyboard-accessible, but we can do even better. For users of assistive technologies like screen readers, we need to programmatically link the trigger element and its tooltip. This is where ARIA (Accessible Rich Internet Applications) attributes come in.

By adding a few ARIA attributes, we provide crucial context that a screen reader can announce to the user.

Here's how we'll upgrade our JavaScript:

  1. Give the tooltip element a role="tooltip" and a unique id.
  2. Add an aria-describedby attribute to the trigger element, pointing to the tooltip's id.

Let's modify our showTooltip function:

function showTooltip(event) {
  const trigger = event.target;
  const tooltipText = trigger.getAttribute('data-tooltip');

  if (!tooltipText) return;

  if (!tooltipElement) {
    tooltipElement = document.createElement('div');
    tooltipElement.className = 'tooltip-js';
    tooltipElement.id = 'dynamic-tooltip'; // 1. Add a unique ID
    tooltipElement.setAttribute('role', 'tooltip'); // 1. Set the role
    document.body.appendChild(tooltipElement);
  }

  // 2. Link the trigger to the tooltip
  trigger.setAttribute('aria-describedby', tooltipElement.id);

  tooltipElement.textContent = tooltipText;
  tooltipElement.style.display = 'block';

  positionTooltip(trigger);
}

function hideTooltip(event) {
  if (tooltipElement) {
    tooltipElement.style.display = 'none';
    // Clean up the ARIA attribute when hiding
    event.target.removeAttribute('aria-describedby');
  }
}

With these changes, when a screen reader user focuses on the trigger, it might announce something like: "Button, Hover Over Me. Has pop-up. This is the tooltip!" This is a massive improvement, transforming a purely visual element into an experience that's accessible to everyone.

One last accessibility touch: allow users to dismiss the tooltip with the Escape key.

// Add this inside your DOMContentLoaded event listener
document.addEventListener('keydown', (event) => {
  if (event.key === 'Escape') {
    hideTooltip();
  }
});

Note: For hideTooltip to work here, you might need to slightly refactor it so it doesn't rely on event.target. A simple fix is to store the current active trigger in a variable when the tooltip is shown.

Section 6: Best Practices and Final Polish

We've built a fantastic, robust tooltip. Here are a few final thoughts and best practices to make it production-ready.

  • Reusability: Wrap your entire logic in a class or a factory function. This makes it easy to instantiate and manage tooltips across your application without polluting the global scope.

    class TooltipManager {
  constructor(selector) {
    // ... move all the logic inside this class
  }
  init() {
    // ... add event listeners
  }
}

new TooltipManager([data-tooltip]).init();

  • Customization with CSS Variables: Make your tooltip easily themeable by using CSS Custom Properties for colors, padding, and more.

    :root {
  --tooltip-bg: #333;
  --tooltip-text-color: #fff;
  --tooltip-arrow-size: 5px;
}

.tooltip-js {
  background-color: var(--tooltip-bg);
  color: var(--tooltip-text-color);
}

.tooltip-js::after {
  border-width: var(--tooltip-arrow-size);
  border-color: var(--tooltip-bg) transparent transparent transparent;
}

  • Performance: Our current implementation is very performant. If you were to build a tooltip that follows the cursor's movement (using the mousemove event), you would need to debounce or throttle your positionTooltip function to avoid performance bottlenecks from firing the event too frequently.

  • Touch Devices: The mouseover event can be problematic on touch screens. It might fire and not go away, or not fire at all. For a truly mobile-friendly experience, you may need to detect touch support and switch to using click or touchstart events to toggle the tooltip's visibility. This changes the interaction model, but is often necessary.

Conclusion

We've come a long way! We started with a simple HTML and CSS snippet and progressively built it into a feature-rich, dynamic, and accessible tooltip component.

We learned:

  • The power of position: relative and position: absolute for basic layout.
  • How to create CSS shapes like triangles using the border trick.
  • The limitations of a CSS-only approach, especially regarding responsiveness and accessibility.
  • How to leverage JavaScript's getBoundingClientRect() for precise, dynamic positioning.
  • The critical importance of handling edge cases, like the tooltip overflowing the viewport.
  • How to use ARIA attributes (role, aria-describedby) to make our UI accessible to screen reader users.

Building a seemingly simple component like a tooltip reveals the depth and thoughtfulness required in modern front-end development. It's a perfect microcosm of the daily challenges we face: balancing aesthetics, functionality, performance, and inclusivity.

Now it's your turn. Take this code, experiment with it, and build upon it. How would you add different placement options (left, right, bottom)? How would you animate the tooltip flipping when it hits the top edge? The possibilities are endless.

Happy coding!

Discuss on Twitter • View on GitHub