@webring-kit/element

Native Web Components for embedding Webring Kit widgets on any website.

This package defines browser-native custom elements that work across static sites, CMSs, and frontend frameworks:

• <webring-nav>
• <webring-list>
• <webring-badge>

The default rendering strategy is light DOM, so the widget can inherit the host page's typography, link color, spacing, and design system. Isolated rendering can be used where stronger style encapsulation is needed.

Install

pnpm add @webring-kit/element

npm install @webring-kit/element

Bundler usage

import "@webring-kit/element";

<webring-nav
  src="/rings/example.json"
  site="https://alice.example.com"
  layout="nav"
  theme="inherit"
  random="true">
</webring-nav>

CDN-style usage

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@webring-kit/element/dist/webring-element.js">
</script>

<webring-nav
  src="https://example.com/rings/indie-devs.json"
  site="https://alice.example.com"
  random="true">
</webring-nav>

No-JS and failure fallback

You can provide fallback content inside the element. By default, Webring Kit restores this content if the ring manifest cannot be fetched.

<webring-nav src="/rings/example.json" site="https://alice.example.com">
  <nav aria-label="Fallback Webring">
    <a href="https://example.com/webring">View the webring</a>
  </nav>
</webring-nav>

Fallback modes:

• fallback="content" restores author-provided child content when available. This is the default.
• fallback="message" renders Webring unavailable.
• fallback="hide" renders nothing.
• fallback="debug" renders detailed fetch/validation errors and should be used only during development.

SSR warning

@webring-kit/element is browser-only. Do not import it from Node scripts, Astro frontmatter, Next.js Server Components, or other server-rendered code. Use a client-side script tag, dynamic import, or framework client boundary.

Safe examples:

// Vite / client-only entry
import "@webring-kit/element";

// Next.js Client Component
"use client";

import { useEffect } from "react";

export function WebringClient() {
  useEffect(() => {
    void import("@webring-kit/element");
  }, []);

  return <webring-nav src="/rings/example.json" />;
}

Attributes

Common attributes for <webring-nav>:

| Attribute | Description | |---|---| | src | URL of the ring JSON manifest. | | site | Current site URL. Defaults to the current page URL when omitted. | | layout | nav, compact, badge, or list, depending on component support. | | theme | inherit, minimal, or isolated. | | random | Adds a random-site link when present. | | target | Link target such as _self or _blank. | | fallback | content, message, hide, or debug. | | cache | Cache mode, if enabled by the implementation. | | cache-ttl | Cache TTL in seconds, if enabled by the implementation. | | label | Accessible label for the rendered navigation. |

Events

The elements emit custom events that host apps can listen for:

document.querySelector("webring-nav")?.addEventListener("webring:load", (event) => {
  console.log("ring loaded", event);
});

document.querySelector("webring-nav")?.addEventListener("webring:error", (event) => {
  console.error("ring failed", event);
});

document.querySelector("webring-nav")?.addEventListener("webring:navigate", (event) => {
  console.log("webring link clicked", event);
});

Styling

The default mode is designed to inherit host-page styles.

webring-nav {
  --webring-gap: 0.75rem;
  --webring-link-color: currentColor;
  --webring-link-decoration: underline;
}

When isolated mode is used, style exposed parts with ::part() where supported by the component.

Related packages

• @webring-kit/core for non-UI logic.
• @webring-kit/react for React wrappers.
• @webring-kit/next for Next.js helpers.
• @webring-kit/cli for manifest validation and maintenance commands.