Using the Web Components in a Hugo Site

This document is for Hugo theme users and site authors. You do not need to understand Web Components to use these.

What These Components Are

These components let you write semantic, readable HTML like:

<my-article title="Hello">
  <p>This is my article.</p>
</my-article>

…and have it turn into clean, accessible HTML automatically.

You do not write JavaScript. You mostly use CSS and HTML templates.

How It Works (High Level)

• The site includes a single JS file that registers all components
• Each <my-*> element renders semantic HTML inside itself
• CSS targets the custom tags and inner elements
• Everything works offline and on static pages

Styling (Most Common Task)

You style components using plain CSS, no classes required.

Example:

my-article my-header h1 {
  font-size: 2.2rem;
}

my-article > article {
  max-width: 70ch;
  margin: auto;
}

Because the custom tags stay in the DOM, they are stable CSS hooks.

Changing Structure (Templates)

If you want to change the HTML structure, you override a template.

Example: override article structure

Add this to a Hugo partial that is included before the JS file:

<template id="my-article-template">
  <article>
    <my-header></my-header>
    <nav>Extra navigation</nav>
    <section my-body></section>
  </article>
</template>

That’s it.

All <my-article> elements now use this structure.

You do not need to edit content files.

You Don’t Have to Provide Templates

If you don’t define any templates:

• The components use built-in defaults
• Everything still works

Templates are optional overrides, not requirements.

Headers Are Automatic

Articles only render headers if they have content:

<my-article title="Hello">

renders a header.

<my-article>

does not.

You can also change how headers look by overriding the header template:

<template id="my-header-template">
  <header>
    <h1 my-title></h1>
    <p my-subtitle></p>
  </header>
</template>

When Do I Need JavaScript?

Almost never.

You only need JS if:

• You want new behavior (not just layout)
• You want a completely different component logic

In that case, you can define your own component with the same tag name.

Common Mistakes to Avoid

• Don’t self-close custom elements (<my-header></my-header>, not <my-header />)
• Don’t duplicate <template id="..."> IDs
• Make sure templates appear before the JS module in the HTML

Mental Model to Keep

• HTML templates = structure
• CSS = appearance
• JS = glue
• Content stays clean and readable

That’s it.