From 94e893bebef333cf65f02ba2df98506b83e864f8 Mon Sep 17 00:00:00 2001
From: Laurent Bardin <laurent.bardin+gitlab@protonmail.com>
Date: Thu, 19 Feb 2026 19:40:43 +0100
Subject: [PATCH] Skip replaced elements when initialising tooltips

Tooltips use `::before` and `::after`, which cannot work on replaced
elements, the most common of which is `<img>`. We skip those elements
when initialising the tooltips so that their `title` attribute is not
removed and it can still be displayed by the browser when hovering over
them.
---
 docs/content/components/tooltip.md | 12 ++++++++++++
 src/js/tooltip.js                  | 12 ++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/docs/content/components/tooltip.md b/docs/content/components/tooltip.md
index 0d05db4..062d415 100644
--- a/docs/content/components/tooltip.md
+++ b/docs/content/components/tooltip.md
@@ -13,3 +13,15 @@ Use the standard `title` attribute on any element to render a tooltip with smoot
 <a href="#" title="View your profile">Profile</a>
 ```
 {% end %}
+
+### Special Elements
+
+The technique used to display these tooltips won't work on a few HTML elements, most notably `<img>`, so the native browser tooltip will be shown. To work around this issue, simply wrap those elements into another (e.g. `<div>` or `<span>`), and move the `title` attribute onto that parent element:
+
+```html
+<span title="A title for the image">
+    <img src="...">
+</span>
+```
+
+Other elements affected by this are `<input type="image">`, `<video>`, `<embed>`, `<iframe>`, `<fencedframe>`, `<audio>`, `<canvas>`, and `<object>`.
diff --git a/src/js/tooltip.js b/src/js/tooltip.js
index 6a012b5..4837cd8 100644
--- a/src/js/tooltip.js
+++ b/src/js/tooltip.js
@@ -6,7 +6,19 @@
 
 document.addEventListener('DOMContentLoaded', () => {
   const _attrib = 'title', _sel = '[title]';
+  // https://developer.mozilla.org/en-US/docs/Glossary/Replaced_elements
+  const _replacedElements = [
+    'img', 'video', 'embed', 'iframe', 'fencedframe',
+    // The following three elements are only sometimes considered replaced, but
+    // we'll skip them nonetheless to at least get the native browser tooltip
+    // if they can have it.
+    'audio', 'canvas', 'object',
+  ];
+  const isReplacedElement = el => _replacedElements.includes(el.localName);
+  const isInputImage = el => el.localName == 'input' && el.type == 'image';
+
   const apply = el => {
+    if (isReplacedElement(el) || isInputImage(el)) return;
     const t = el.getAttribute(_attrib);
     if (!t) return;
     el.setAttribute('data-tooltip', t);