Installation

Hypermedia Components ships as one CSS file, one behaviors bundle, and an optional macros bundle. Always load the CSS; load the JS only if you use the interactive behaviors.

CDN (no build step)

The fastest way to try HC — and a perfectly fine way to run it — is two tags straight off jsDelivr:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@hypermedia-components/core/dist/hc.min.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@hypermedia-components/core/dist/hc.behaviors.min.js"></script>

That’s every component and every behavior, ~74 KB gzip total (CSS + JS; Brotli, which CDNs usually serve, is smaller). In production, pin a version (…/npm/@hypermedia-components/core@<version>/dist/…) so a release can’t change your page underneath you — and see Versioning & stability for what counts as public API before you bump a pin. Exact sizes, granular per-component loading, and an import-map variant live on Bundle size & imports.

With a bundler (npm)

npm install @hypermedia-components/core

import '@hypermedia-components/core/css';       // the styles
import '@hypermedia-components/core/behaviors';  // auto-installs every behavior

The /behaviors entry is side-effecting: importing it installs every behavior once the DOM is ready. To pull in only the behaviors you use, import the individual installers instead — see Behaviors.

Without a bundler (static files)

No build step? Copy the prebuilt files out of node_modules/@hypermedia-components/core/dist/ (or a release download) into a static folder and reference them directly:

<link rel="stylesheet" href="/assets/hc/hc.min.css">
<script type="module" src="/assets/hc/hc.behaviors.min.js"></script>

Use the .min.js bundle here — it is self-contained. (The un-minified hc.behaviors.js is the bundler entry; it imports sibling modules, so it will not load on its own from a <script> tag.) The Plain HTML guide has a complete copy-paste page, including the toast region and an htmx round trip.

Behaviors

CSS components render on their own. Interactive ones — menus, dialogs, toasts, comboboxes, and so on — need a small JS behavior. You have two options:

• All at once — import '@hypermedia-components/core/behaviors'; installs every behavior automatically (this is what the docs site and the integration guides use).

• Pick and choose — import only the installers you need:

  import { installMenu, installToast } from '@hypermedia-components/core';
  installMenu();
  installToast();

Every installX() is idempotent (safe to call again — e.g. after an htmx swap) and returns an uninstaller. Each component and recipe page names the behavior it needs.

htmx (for recipes)

Components and behaviors work without htmx. The recipes — and every data-hx-* attribute in these docs — additionally need htmx, which you load yourself; HC never bundles it:

<script defer src="https://unpkg.com/htmx.org@2"></script>

Pin the exact version in production (see htmx’s install docs). HC’s docs write htmx attributes in the data-hx-* form (htmx accepts both) — the htmx integration guide covers loading, CSRF, and the response-header conventions.

Troubleshooting

• Interactive components render but don’t respond (menus don’t open, toasts don’t stack) — the behaviors bundle isn’t loaded, or you loaded the un-minified hc.behaviors.js from a <script> tag (see the note above — use .min.js there).
• data-hx-* attributes do nothing — htmx itself isn’t on the page; it is a separate script (see htmx).
• Components inside htmx-swapped fragments stop working — the auto-init /behaviors bundle re-scans after swaps, so this only happens with hand-picked installers; call the relevant installX() again after the swap (it’s idempotent).

Next steps

• Quick start — a minimal page, built up step by step.
• Components — every component with live examples.