🧩 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

Core API

import {
  // Component Creation
  component,
  
  // Template & Styling
  html,
  css,
  
  // Reactive State
  ref,
  computed,
  watch,
  
  // Hooks
  useProps,
  useEmit,
  useOnConnected,
  useOnDisconnected,
  useOnAttributeChanged,
  useOnError,
  useStyle,
  
  // Directives
  when,
  each,
  match,
  anchorBlock,
  
  // Directive Enhancements
  unless,
  whenEmpty,
  whenNotEmpty,
  eachWhere,
  switchOnLength,
  eachGroup,
  eachPage,
  switchOnPromise,
  whenMedia,
  responsive,
  mediaVariants,
  responsiveOrder,
  
  // Transitions
  Transition,
  TransitionGroup,
  transitionPresets,
  createTransitionPreset,
  getTransitionStyleSheet,
  
  // Event Bus
  eventBus,
  emit,      // Shorthand for eventBus.emit
  on,        // Shorthand for eventBus.on
  off,       // Shorthand for eventBus.off
  once,      // Shorthand for eventBus.once
  listen,    // DOM event listener wrapper
  
  // Store
  createStore,
  
  // Router
  useRouter,
  initRouter,
  matchRoute,
  matchRouteSSR,
  parseQuery,
  
  // SSR & Types
  renderToString,
  VNode,
} from '@jasonshimmy/custom-elements-runtime';

📖 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

🔗 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!