New May 7, 2025

Glossary Web Component

More Front-end Bloggers All from dbushell.com (blog) View Glossary Web Component on dbushell.com

I’ve added a secret glossary to my blog! You might find it by hovering over special links. Don’t tell anyone, it’s a secret. At least until I can find a way to style the links without them being a distraction. Do I need to, or can they remain easter eggs?

The Idea

This project came about when I noted concern over my reliance on MDN. I always favour MDN over other sources. I’m lazy. I feel guilty for not linking to the small web, the indie web, the weird web. At first I banned myself from linking to MDN. Later I mulled over the glossary idea. I think I’ve solved it!

The Implementation

I write my blog posts in Markdown. For new glossary terms I now link to a placeholder rather than an external source. For example:

[React](/glossary/react.json)

This references a JSON file that has the following format:

{
  "title": "React",
  "description": "A legacy JavaScript framework (turned religion). Favoured by tech bros and famous for bloated bundles and crippling web performance.",
  "links": [
    {
      "name": "JSX.lol",
      "title": "Does anybody actually like React?",
      "url": "https://jsx.lol"
    },
    {
      "name": "React",
      "url": "https://react.dev"
    }
  ]
}

My build script replaces the markdown link with a web component:

<glossary-term id="--term-react">
  <a href="https://jsx.lol">React</a>
</glossary-term>

The first link in the JSON is used as the canonical source.

HTML wrapped in a custom element is a perfect example of progressive enhancement. For unsupported browsers there is still an accessible link inside. For browsers that support the Popover API each <glossary-term> element is enhanced with a fancy popover.

If you’ve missed every example so far here is the React link.

I captured a screen recording of how it should appear:

The popover is activated by either hover or keyboard focus. The escape key can also dismiss them. For touchscreens I’m going to test that live…

[INSERT TEST RESULTS]

Test results: it works fine. If you’ve got one of those new Apple Pencils — the new new one, not the new old one — the hover effect is magical. Touch taps are taken straight to the canonical link. The popover might be open upon return. Maybe I should cancel the popover based on touch events to avoid confusion?

Failures

Initially I tried to use CSS anchor positioning.

I really tried. It left me in tears and I rage quit. It might be the most unintuitive, doesn’t work like it says, infuriating web “standard” ever. When anchoring a popover it’s impossible to ensure elements stay inside the viewport (without JavaScript). Please prove me wrong!

I tried to get creative with view transitions and failed. Safari had some pixel-shifting jank going on. I tried normal transitions with allow-discrete and @starting-style and failed. In an isolated demo it’s all gravy but together this new CSS stuff doesn’t plays nice. It’s not all baseline yet so let’s hope it improves. 🤞

CSS anchors are Chrome and Chrome derivatives only right now. Safari Technical Preview claims to have support but Apple lies under oath so who knows?

Ultimately I gave up and used JavaScript to calculate position so I can support all browsers. I’ll recharge morale and tackle a v2.0 at a later date.

Bookmarking

I don’t plan to immediately retrofit older blog posts with glossary links. Although that could be a quick find & replace if I’m careful. I’m looking for positive feedback before I do. So let me know if you like it (or not). If no one hates it I’ll plough ahead, because I like it. This glossary may just be the third incarnation of my bookmarks blog.

I’m tempted to use a similar technique to create popover cards for linked notes. They have more content so I need to consider that more.

Scroll to top