Heartml is Postmodern HTML. 🍭
Web components that just can't get enough of that sweet declarative markup. 🥰

Heartml is a versatile new web component format, centered around present-day open standards and running in the direction of future ones.

You can define Heartml components entirely in JavaScript, in declarative Single-File Component HTML module files, or simply embedded directly in any HTML page. Build steps? Completely optional!

Write split components (all markup is rendered server-side, then upgraded with client-side behavior), hybrid components (markup from server, but shipping with a template so new components can be initialized on the client), or client-side only components—you decide!

Forget everything you know about web components…and fall in love with them all over again.

Features! So Many Features!

Every Component Everywhere All at Once

Server-agnostic: emit SSR via Ruby today, JavaScript coming soon. Other renderers entirely possible.
Or you can integrate with existing server component formats such as WebC.
Use Heartml all by itself or alongside other web components built with vanilla JS, Lit, Stencil, etc.
Run Heartml everywhere! It works seamlessly in all kinds of stacks, from WordPress to Ruby on Rails to Eleventy.

Choose Your Flavor

Most features work in light DOM and in shadow DOM, sometimes simultaneously!
Heartml is Declarative Shadow DOM-ready and compatible with HTML over the wire tooling such as Turbo.
Signals (a minimalist bundled dependency) provides for fine-grained reactivity and even coordinated client state across multiple components.
Heartml modules can be loaded directly in buildless environments or bundled up via a straightforward esbuild plugin.

Extensible by Design

98% of functionality is located in plugins, rather than the base class. (And you can assemble your own base class if you really want to.)
Write your own plugins! They’re “composable” behaviors which components can opt into via both JavaScript and declarative HTML.
Package provides unbundled ESM, or install a pre-bundled/minified version right off a CDN.
All of Heartml fits in a tiny ~5KB compressed size—even including Signals. Did we mention this thing is tiny? 😆

How to Install

From a CDN:

<head>
  <script src="https://cdn.jsdelivr.net/npm/heartml@latest"></script>
</head>

From a package:

npm i heartml

import { HeartElement } from "heartml"

Heartml in Action

Declarative Custom Elements (DCEs)

Heartml lets you define custom elements declaratively directly in your HTML using heart-ml tags. This is particularly useful for co-locating components with specific use cases right in the contexts where they’ll be used.

Heartml Module Files (SFCs)

Moving a step up from DCEs, you can author .heartml files—a Single-File Component format which starts with pure HTML. You can import and bundle .heartml files via esbuild or alternatively use the <heart-module> custom element to load them up in any “buildless” environment.

Write a Plugin

Virtually all Heartml functionality is provided by plugins. Every static property on your class is checked to determine if it should activate a plugin. So writing your own is simply a matter of adding some code to the Hearml.plugins object, and using that key as a static property on your component class.

This pattern doubles as a configuration mechanism, and even works as pure JSON within declarative custom element attributes! (Any kebob-case plugin attribute gets converted to camelCase automatically.)

Works Great with Design Systems…Like Shoelace!

If it’s another custom element, you’re golden. Mix ‘n’ match however you like. Just keep an eye on your total bundle size. (But if you employ Islands Architecture and use tools like <is-land>…might not even matter!)

Next Steps

Peruse the Documentation to learn more about the various features of the Heartml component format, including how to work with signals and effects, how to control hydration through “lazy” effects, how to handle events, how you can manage shared state across multiple components, and how to add shared component behaviors via plugins.

For server-side rendering (SSR), read our Ruby Components documentation. We hope to support more SSR languages in the future, such as JavaScript.

Where is Heartml Being Used?

The largest production rollouts of Heartml to date are on the Preset Galaxy and The Spicy Web websites. You can see Heartml in action on Preset Galaxy in the form of the audio player, comments section, and several other interactive elements across various features. On The Spicy Web, Heartml handles the account “drawer”, paywall access to content, and some other aspects of the content experience.

Now that Heartml is available to the public, we hope to see usage blossom in a variety of settings!

Who’s Developing Heartml?

Heartml is developed by Jared White, the creator of Bridgetown and a freelance web solutions architect with Whitefusion. It was conceived in fall of 2022, and released as a beta to the public in early 2024.

Competing Solutions

While Heartml is an original solution, it gets its inspiration from a variety of sources. The idea of a single-file component with separate tags for the HTML template, CSS, and JavaScript was popularized by Vue, and petite-vue was a particular point of inspiration. There are hints of features popularized by Lit, a well-known web component library. The proposed HTML Modules spec and our subsequent esbuild plugin was also a launching pad for a library like Heartml.

From an HTML-first perspective, other solutions you may have come across are WebC and Enhance, which both offer ways to server-render web components and related HTML constructs. While Heartml was born independently and evolved in parallel to those projects, you’ll notice some definite similiaries (as well as plenty of differences!). We believe “a rising tide floats all boats” and the more examples of using web component-esque solutions in various web frameworks there are around the industry—and especially in multiple server languages besides just JavaScript—the better!

Contributing to Heartml

…