🧩 Custom Elements Runtime

The Complete Web Components Framework

Build modern components with strict TypeScript, zero dependencies, and a clean functional API. Designed for speed, standards compliance, and productivity.

🕹️ Try it on Codepen.io.

✨ Why You'll Love It

• ⚡ Blazing Fast: Minimal runtime, instant updates, zero dependencies.
• 🎨 JIT CSS: On-demand, utility-first styling directly in your HTML at runtime.
• 💪 No Build Necessary: Instant development feedback, no bundling required.
• 🧑‍💻 TypeScript First: Strict types, intellisense, and safety everywhere.
• 🧩 Functional API: No classes, no boilerplate—just pure functions.
• 🛠️ SSR & HMR Ready: Universal rendering and instant hot reloads.
• 🔌 Extensible: Directives, event bus, store, and more for advanced use cases.
• 🏆 Developer Friendly: Clean docs, examples, and a welcoming community.

⏱️ Getting Started

1. Install: npm install @jasonshimmy/custom-elements-runtime
2. Create a Component:

import {
  component,
  ref,
  html,
  useEmit,
  useProps,
} from '@jasonshimmy/custom-elements-runtime';

component('my-counter', () => {
  const props = useProps({ initialCount: 0 });
  const count = ref(props.initialCount);
  const emit = useEmit();

  const handleClick = () => {
    count.value++;
    emit('update:initial-count', { count: count.value });
  };

  return html`
    <button
      type="button"
      class="px-4 py-2 bg-primary-500 text-white rounded"
      @click.prevent="${handleClick}"
    >
      Count: ${count.value}
    </button>
  `;
});

3. Use in HTML:

<my-counter
  initial-count="5"
  @update:initial-count="handleCountUpdate"
></my-counter>

<script>
  function handleCountUpdate(event) {
    console.log('Count updated to:', event.detail.count);
  }
</script>

4. Enjoy instant reactivity and type safety!

📦 Complete API Reference

Below is the complete list of public symbols exported by the runtime and its named subpaths (root entry + subpath entries).

Root Entry

Package: @jasonshimmy/custom-elements-runtime

Export	Description
component	Define a custom element with the functional component API.
html	Template tag function producing runtime VNodes from template literals.
css	Define component-scoped/JIT styles or register stylesheets.
ref	Create a reactive reference object with a .value property.
computed	Create a derived, read-only reactive value from other reactives.
watch	Register watchers reacting to changes in reactive values.
useProps	Hook to declare/consume typed component props with defaults.
useEmit	Hook returning an emit function for dispatching custom events.
useOnConnected	Hook that runs a callback when the component connects.
useOnDisconnected	Hook that runs a callback when the component disconnects.
useOnAttributeChanged	Hook observing host attribute changes.
useOnError	Hook to register a component-level error handler.
useStyle	Hook to register or compute component styles at runtime.
unsafeHTML	Insert raw HTML into a template (unsafe; use carefully).
decodeEntities	Utility to decode HTML entities in strings.

---

Directives

Package: @jasonshimmy/custom-elements-runtime/directives

Export	Description
when	Conditional rendering: render children when the condition is true.
each	Iterate arrays and render a VNode per item with stable keys.
match	Fluent branching API (when/otherwise/done) returning VNodes.
anchorBlock	Create a stable anchor VNode used as block boundaries.

---

Directive Enhancements

Package: @jasonshimmy/custom-elements-runtime/directive-enhancements

Export	Description
unless	Inverse of when (render when condition is false).
whenEmpty	Render content when a collection is empty or null.
whenNotEmpty	Render content when a collection has items.
eachWhere	Filter + iterate; render only items matching a predicate.
switchOnLength	Render different content based on array length cases.
eachGroup	Group array items by a key and render per-group content.
eachPage	Render a paginated subset (page) of items.
switchOnPromise	Render loading/success/error/idle states for async data.
whenMedia	Render content when a CSS media query matches.
mediaVariants	Map of responsive media queries (sm, md, lg, xl, 2xl, dark).
responsiveOrder	Ordered breakpoint keys used by responsive helpers.
responsive	Per-breakpoint helpers (sm/md/lg/xl/2xl/dark).
whenVariants	Compose multiple variants (e.g., dark + lg) into one media query.
responsiveSwitch	Render different content for different breakpoints.
switchOn	Fluent switch/case API matching a value to content.

---

Transitions

Package: @jasonshimmy/custom-elements-runtime/transitions

Export	Description
Transition	Wrap content with enter/leave transition metadata consumed by the runtime.
TransitionGroup	Animate lists with enter/leave/move transitions for children.
transitionPresets	Built-in transition presets (fade, slide, scale, etc.).
createTransitionPreset	Create a reusable transition preset programmatically.
getTransitionStyleSheet	Obtain the CSSStyleSheet used by the transition runtime.
Types	TransitionClasses, TransitionHooks, TransitionOptions, TransitionGroupOptions

---

Event Bus

Package: @jasonshimmy/custom-elements-runtime/event-bus

Export	Description
EventHandler	Type: callback signature used by the event bus.
GlobalEventBus	Class: singleton implementing a global pub/sub event bus.
eventBus	Proxy: lazy proxy to the singleton GlobalEventBus instance.
emit	Emit a global event with an optional payload.
on	Register a handler for a global event (returns unsubscribe function).
off	Remove a handler for a global event.
once	Register a one-time handler; returns a Promise resolving with the payload.
listen	Listen for native CustomEvent on the global event bus (returns unsubscribe).

---

Store

Package: @jasonshimmy/custom-elements-runtime/store

Export	Description
Store	Interface describing subscribe / getState / setState.
createStore	Create a simple observable store that notifies subscribers.

---

Router

Package: @jasonshimmy/custom-elements-runtime/router

Export	Description
useRouter	Create and use a router instance configured with routes (client & SSR).
initRouter	Initialize the router and register router-view / router-link.
matchRoute	Match a path against configured routes and extract params.
matchRouteSSR	SSR-friendly wrapper for route matching.
parseQuery	Parse a query string into a key/value map.
resolveRouteComponent	Resolve/load a route's component (supports async loaders + caching).
Types	Route, RouteState, RouteComponent, GuardResult, RouterLinkProps, RouterLinkComputed, RouterConfig

---

SSR

Package: @jasonshimmy/custom-elements-runtime/ssr

Export	Description
renderToString	Render a VNode tree to HTML for server-side rendering.
VNode (type)	The runtime VNode shape used by renderers and SSR.

Global Styles (CSS)

Package: @jasonshimmy/custom-elements-runtime/css or @jasonshimmy/custom-elements-runtime/css/style.css

Export	Description
style.css	CSS export that contains CSS variables and a base reset.

Variables (CSS)

Package: @jasonshimmy/custom-elements-runtime/css/variables.css

Export	Description
variables.css	CSS export that contains design tokens (colors, fonts, etc.).

Reset (CSS)

Package: @jasonshimmy/custom-elements-runtime/css/reset.css

Export	Description
reset.css	CSS export that contains a base reset for styles.

📖 Documentation Index

Explore the complete documentation for every runtime feature:

🚀 Getting Started

• 🎯 Functional API - Start here! Complete guide to the modern functional component API

🏗️ Core Features

• 🧩 Template - Template syntax and html function
• 🧭 Directives - Conditional rendering with when, each, and match
• 🛠️ Directive Enhancements - Advanced directive utilities:
  • unless - Inverse of when
  • whenEmpty / whenNotEmpty - Collection checks
  • eachWhere - Filtered iteration
  • switchOnLength - Render based on array length
  • eachGroup - Group and render items
  • eachPage - Pagination support
  • switchOnPromise - Async state rendering
  • whenMedia - Media query responsive rendering
  • responsive - Responsive utilities
• 🔗 Bindings - Data binding with :prop, @event, :model, :class, :style
• 🔔 Events Deep Dive - Custom event emission and handling patterns
• 🎬 Transitions Guide - Animation and transition effects

🎨 Styling

• 🎨 JIT CSS - On-demand utility-first styling system
• 📝 Prose Typography - Beautiful typography for long-form content

🔗 Communication & State

• 📢 Event Bus - Global event system for cross-component communication
• 🗄️ Store - Global state management
• 🚦 Router - Client-side routing
• 🤝 Cross-Component Communication - Patterns for component interaction

⚡ Advanced Features

• 🔮 Virtual DOM - VDOM implementation and performance details
• 🌐 SSR - Server-side rendering support
• ♻️ HMR - Hot module replacement
• 🛡️ Infinite Loop Protection - Runtime safeguards against infinite loops
• 🔒 Secure Expression Evaluator - Safe evaluation of dynamic expressions in templates

🔧 Integration Guides

• ⚛️ React Integration - Using components in React apps
• 🦊 Vue Integration - Using components in Vue apps
• 🅰️ Angular Integration - Using components in Angular apps
• 🔥 Svelte Integration - Using components in Svelte apps

🛠️ Troubleshooting

• 🔧 Troubleshooting - Common issues and solutions

For examples and implementation details, explore the source code in src/lib/.

🧑‍🔬 Real-World Examples

• Form Input & Validation
• Minimal Example
• Shopping Cart
• Todo App

🌟 Showcase & Community

• Showcase your components! Open a PR to add your project to our gallery.
• Questions or ideas? Start a discussion or open an issue.
• Contribute: We welcome PRs for docs, features, and examples.
• ❤️ Like what you see? Support ongoing development on Patreon

💖 Support This Project

Custom Elements Runtime is a labor of love built to make modern web development faster and more expressive. If it's helping you build better components, consider supporting me on Patreon to help keep the momentum going.

Your support helps fund continued development, documentation, and community engagement. Every bit helps—thank you!