Callee

Callee is excited you’re going to build some components!

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

Choose Your Flavor

Extensible by Design

How to Install

From a CDN:

<head>
  <script src="https://cdn.jsdelivr.net/npm/heartml@0.18.0"></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