Markup

Reactive HTML Templating System

Markup is a JavaScript reactive templating system built to simplify how you build Web user interfaces using web standards with minimal enhancements to the native web APIs as possible.

It consists of 3 main APIs with additional utilities to simplify things even further:

• html: A JavaScript tagged function that allows you to represent the DOM using a template literal string;
• state: A simple state tracking API that allows you to define reactive data as you wish;
• effect: A straight forward way to define things that need to happen when certain states change;

Motivation

JavaScript, Web Standards and APIs give you everything you need to build any web project you want. What is often painful to deal with is the DOM and reactivity, especially as the project gets bigger or require multiple people collaboration.

Markup was created to give you all the reactivity you need while making it simple to define your HTML in JavaScript without introducing a new syntax, or requiring a build, or a big library you need to ship to the client.

From this:

let count = 0

// tedious DOM definition and manipulation
const p = document.createElement('p')
p.textContent = `count: ${count}`

const btn = document.createElement('button')
btn.type = 'button'
btn.textContent = 'count up'

// limiting event driven
btn.addEventListener('onclick', () => {
    count += 1
    p.textContent = `count: ${count}`

    if (count > 10) {
        alert('You counted passed 10!')
    }
})

document.body.append(p, btn)

To this:

// reactive data
const [count, updateCount] = state(0)

// data driven
effect(() => {
    if (count() > 10) {
        alert('You counted passed 10!')
    }
})

const countUp = () => {
    updateCount((prev) => prev + 1)
}

// reactive DOM/templates
html`
    <p>count: ${count}</p>
    <button type="button" onclick="${countUp}">count up</button>
`.render(document.body)

How does it work?

Markup uses template literals and Functions to do everything.

• Functions: JavaScript functions are perfect for lazy evaluations which makes it perfect for reactivity. Markup uses functions everywhere, from internals, defining state, effects, utilities, etc.
• Template Literals: The template literal is used to represent HTML in JavaScript and to avoid to reinvent the wheel. Everything else is enforced by web standards.

Literally everything else is how you know it to be in plain HTML, CSS and JavaScript.

We believe in a simple way to build the web without the jargon of a framework, complex project setups, new syntax, all to spit out HTML, CSS and JavaScript at the end.

Examples

This is a simple example of a button, but you can check:

• A Modular Todo App
• A Simple Counter App
• A Simple Time App

Install

npm install @beforesemicolon/markup

or

yarn add @beforesemicolon/markup

Use directly in the Browser

This library requires no build step. The CDN browser build is about 13.9 KB gzip (40.2 KB uncompressed, measured from dist/client.js).

<!-- Grab the latest version -->
<script src="https://unpkg.com/@beforesemicolon/markup/dist/client.js"></script>

<!-- Or a specific version -->
<script src="https://unpkg.com/@beforesemicolon/[email protected]/dist/client.js"></script>

Usage

<div id="app"></div>

<script>
    const { html, state, effect } = BFS.MARKUP

    html`<h1>Hello World</h1>`.render(document.getElementById('app'))
</script>

BFS.MARKUP exposes the same runtime APIs as the ESM entry point, including helpers such as visible and trusted-markup utilities such as unsafeHTML.

Dynamic values belong in html interpolations. Markup applies those values without parsing them as HTML:

const message = '<strong>hello</strong>'
html`<p>${message}</p>` // renders the markup characters as text

When trusted or independently sanitized markup must be parsed deliberately, use the explicit unsafeHTML API. Never pass user-controlled content to it:

import { unsafeHTML } from '@beforesemicolon/markup'

const trustedIcon = unsafeHTML('<svg aria-hidden="true">...</svg>')

Serialization and event safety

toString() escapes text at the template root as well as inside elements and preserves HTML comments. It rejects content that could escape a script, style, or other text container when the result is parsed again. For JSON data blocks, escape every < after calling JSON.stringify:

const json = JSON.stringify(data).replace(/</g, '\\u003c')
const output = html`<script type="application/json">
    ${json}
</script>`.toString()

Script and style interpolations still require trusted code; Markup does not sanitize JavaScript or CSS. Boundary checks ignore tag-name casing and apply across namespaces, including SVG/MathML nodes that may reparse as HTML. These conservative checks also apply inside foreign-namespace wrappers. See the SSR documentation for serialization restrictions and migration details.

Dynamic on* event bindings accept one function or [function, options] interpolation, optionally surrounded by whitespace. String handlers and mixed literal/interpolated event strings are rejected. Use onclick="${handleClick}" instead of constructing inline JavaScript. Explicitly observed, non-native custom-element properties such as one remain ordinary property bindings. Templates can be constructed before the custom element is registered; define the element before mounting so those properties can be recognized. Deferred mixed event bindings are rejected before any binding is evaluated or written. When a mounted binding receives a new handler, Markup updates a stable delegating listener instead of removing and adding a DOM listener. once is rearmed for the new binding, while changes to capture, passive, or signal still replace the native registration so browser semantics remain intact.

AI and agent context

• llms.txt is the concise, package-owned API contract and coding guide for AI tools.
• llms-full.txt contains the complete resolved documentation and examples.

The source for the concise contract lives in docs/llms.txt, so its behavior and recommendations are reviewed and versioned with Markup.

Ecosystem

• Web Component adds reactive native Custom Elements and re-exports Markup.
• Router adds URL navigation, route elements, guards, and route data on top of Web Component.
• Intl adds locale scopes, messages, and internationalized formatting on top of Web Component.

Router and Intl are complementary and can be used together. Markup remains the shared rendering and reactivity foundation across all packages.

Community

• Contributing guidelines
• Code of Conduct
• Security policy
• BSD 3-Clause License