nimble-html

A light-weight single-file dependency-free template tag library with html, svg, and mathml functions for writing declarative-reactive web apps.

Nimble like Grogu.

At a glance

import {html, svg, mathml} from 'nimble-html'

let colors = ['red', 'green', 'blue']
const feeling = 'simplicity'

const key = Symbol()

const template = () => html`
  <ul .onclick=${() => console.log(feeling)}>
    ${colors.map(c => html`<li>${c}</li>`)}
  </ul>

  <svg width="100" height="100">
    ${colors.map((c, i) => svg` <circle cx="50 + ${i}" cy="50 + ${i}" r="40 + ${i}" fill=${c}/> `)}
  </svg>

  <math> ${colors.map((c, i) => mathml` <mfrac> <mi>${i}</mi> <mi>${c}</mi> </mfrac> `)} </math>
`(key),

document.body.append( ...template())

// Update values any time.
colors = ['cyan', 'magenta', 'yellow', 'black']
template() // updates the DOM

Features

Zero dependencies: Lightweight implementation using standard DOM APIs, in a single small file
Framework-agnostic: Works with any JavaScript framework or no framework at all
Multi-namespace support: html, svg, and mathml template tags with proper namespace handling
Declarative and reactive: Update DOM by re-invoking templates with new values
buildless: No build step required, works in any modern browser as-is
Template caching: Templates are cached based on source location for optimal performance
Instance management: Unique keys create unique DOM instances that can be updated in place
Attribute and property binding: Supports regular attributes, boolean attributes, JS properties, and event handlers
Case-sensitive bindings: Property and event bindings preserve exact case for maximum compatibility
Type-safe: Written in plain JavaScript with JSDoc types for TypeScript compatibility
Lit-compatible syntax: Uses familiar template syntax for easy adoption

A closer look

import {html} from 'nimble-html'

let value = 'Hello World'

const key = Symbol() // or any unique value

// Value interpolation
const template = () => html`<div>Message: ${value}</div>`(key)

const [div] = template() // Creates and returns DOM

console.log(div instanceof HTMLDivElement) // true
console.log(div.textContent) // "Message: Hello World"

// Update values any time.
let value = 'Hello Webdev'
template() // updates the DOM

console.log(div.textContent) // "Message: Hello Webdev"

Examples

Basic - source
Custom Elements - source

Installation

Simply copy html.js to your project, or import it directly from GitHub into your JS code (f.e. using the raw.githack.com proxy):

<script type="module">
  import {html, svg, mathml} from 'https://rawcdn.githack.com/lume/nimble-html/v0.1.4/html.js'

  const feeling = 'wonderfulness'
  const [div] = html`<div>${feeling}</div>`()

  document.body.append(div)
</script>

If you want to keep your app import statements clean, define an importmap:

<script type="importmap">
  {
    "imports": {
      "nimble-html": "https://rawcdn.githack.com/lume/nimble-html/v0.1.0/html.js"
    }
  }
</script>

<script type="module">
  import {html, svg, mathml} from 'nimble-html'

  const feeling = 'wonderfulness'
  const [div] = html`<div>${feeling}</div>`()

  document.body.append(div)
</script>

If you have Node.js tooling, you can also install it via npm:

npm install nimble-html

Key Concepts (pun intended)

Template Identity and Keying

Template instances are formed by two things:

Source location - The unique template strings array from your source code
Key - A unique reference you provide for instance identity when calling the template

Each template instance has a unique DOM tree that can be updated in place by repeatedly calling the same template with the same key.

const key = Symbol() // A key to represent a single template instance.

function render(key, value) {
  return html`<div>Value: ${value}</div>`(key)
}

const [div1] = render(key, 'first')
document.body.append(div1)

console.log(div1.textContent) // "Value: first" - initial content

const [div2] = render(key, 'second')

console.log(div1 === div2) // true - same DOM instance!
console.log(div1.textContent) // "Value: second" - content updated

const newKey = Symbol() // A different key for a new template instance.
const [div3] = render(newKey, 'third')

console.log(div2 !== div3) // true - new DOM instance
console.log(div3.textContent) // "Value: third" - new content

This key feature (pun intended) enables higher-level frameworks to build different ways of managing template instances, while being simple out of the box.

Attribute Types

The library supports different attribute binding syntaxes:

const value = 'dynamic'
const isEnabled = true
const clickHandler = () => console.log('clicked')

const elements = html`
  <!-- Regular attributes -->
  <div class=${value}></div>
  <div class="${value} static-class"></div>

  <!-- Boolean attributes (with ? prefix) -->
  <input ?disabled=${!isEnabled} />

  <!-- JS properties (with . prefix) -->
  <input .value=${value} />

  <!-- Event handlers (with @ prefix) -->
  <button @click=${clickHandler}>Click me</button>
`(key)

Case Sensitivity for Properties and Events

Property bindings (.prop=) and event bindings (@event=) preserve exact case, allowing you to target specific JavaScript properties and events:

const element = html`
  <div
    .customProp=${'value1'}     <!-- Sets element.customProp -->
    .customprop=${'value2'}     <!-- Sets element.customprop (different property!) -->
    @customEvent=${handler1}    <!-- Listens for 'customEvent' -->
    @customevent=${handler2}    <!-- Listens for 'customevent' (different event!) -->
  ></div>
`(key)

// Both properties are set independently
console.log(element.customProp) // 'value1'
console.log(element.customprop) // 'value2'

// Both event listeners are registered independently
element.dispatchEvent(new Event('customEvent')) // Calls handler1
element.dispatchEvent(new Event('customevent')) // Calls handler2

This case sensitivity is particularly important for:

Custom elements with camelCase properties like .firstName, .lastName
Framework integration where exact property names matter
Custom events that may use different casing conventions

Get Multiple Elements

An html template returns an array of nodes for convenient access:

const elements = html`
  <div>First element</div>
  <p>Second element</p>
`(key)

console.log(elements) // [div, p]

A useful syntax is array destructuring to grab elements or text nodes that are visually visible at the top level of a template:

const [div, button, textNode] = html`
  <div>harmony</div>
  <button>peace</button>
  ${'compassion'}
`

console.log(div.textContent) // harmony
console.log(button.textContent) // peace
console.log(textNode.data) // compassion

Whitespace Handling

The template syntax is standard HTML, including all whitespace handling, except for whitespace at the top level of a template, for convenience. Top level whitespace is trimmed out, and the list of returned nodes are those that you visually see. That's why the return value in the previous example is three items ([div, button, textNode]), and not seven.

The only text nodes returned are those that are visible via an interpolation site.

If you need white space preservation, use explicit text nodes at the top level, or wrap text in elements:

const [pre, whitespace, span, p] = html`
  <pre>   preserved      whitespace   here  </pre>

  ${'   ' /* explicit top-level whitespace */}

  <span> preserved whitespace here </span>

  <p>
    preserved whitespace here

    <span> preserved whitespace here </span>
  </p>
`

You see four nodes, you get four nodes.

Warning

Whitespace handling may be subject to change. Perhaps it is better to preserve all whitespace as-is, for consistency, while still allowing the return value to return visible nodes only. Feedback welcome!

Nested Templates

html templates can be nested inside other templates:

function itemTemplate(name) {
  return html`<li>${name}</li>`
}

function listTemplate(key, items) {
  return html`
    <ul>
      ${items.map(item => itemTemplate(item))}
    </ul>
  `(key)
}

let items = ['apple', 'banana', 'cherry']

const myListKey = Symbol()

document.body.append(...listTemplate(myListKey, items))

It is not required to pass a key to nested templates, and in that case the nested template instance will be unique per parent template instance. In other words, for each parent template instance, there will be a single instance of a child template at a given interpolation site unless a different key is specified for the child template.

With that in mind, this will work as expected and will update the list items in place when the parent listTemplate is called again with the same myListKey:

items = ['avocado', 'blueberry', 'clementine']

listTemplate(myListKey, items)

Event Handlers

Event handlers can be functions or strings:

const handleClick = event => {
  console.log('Button clicked!', event.target)
}

const button = html`
  <!-- Function handler -->
  <button @click=${handleClick}>Click me</button>

  <!-- String handler (evaluated as code) -->
  <button @click="alert('Hello!')">Alert</button>
`(key)

The @event= syntax uses addEventListener under the hood. This is especially useful for custom elements that don't implement event handlers via JS properties like native elements do, f.e. el.oninput = () => {...}.

With property-based event handlers such as .onclick, setting up an event handler using html, like this,

const [el] = html`<button .onclick=${() => {...}}></button>`

is the same as setting it up with the JS property directly:

const el = document.createElement('button')
el.onclick = () => {...}

The .onevent= syntax is not doing anything special with event handlers, it is literally just setting a JS property exactly as specified (some elements just so happen to accept function values for various properties, f.e. event handlers).

With that in mind, the @event= syntax is special in that it is not setting a JS property, but setting up event listeners with add/removeEventListener(), regardless if the element has JS properties that accept event handler functions (most custom elements in the wild do not have such event handler JS properties).

SVG and MathML Support

The library provides dedicated svg and mathml template tag functions that create elements with proper namespaces in the absence of <svg> or <math> root elements:

import {html, svg, mathml} from 'nimble-html'

const key = Symbol()
const radius = 25
const color = 'red'
const width = 30
const height = 30

// SVG elements are created with proper SVG namespace (without needing a wrapping <svg>)
const [circle, rect] = svg`
  <circle cx="50" cy="50" r=${radius} fill=${color}/>
  <rect x="10" y="10" width=${width} height=${height} fill="blue"/>
`(key)

console.log(circle instanceof SVGCircleElement) // true
console.log(rect instanceof SVGRectElement) // true

// MathML elements are created with proper MathML namespace (without needing a wrapping <math>)
const numerator = 'a'
const denominator = 'b'
const [mfrac] = mathml`
  <mfrac>
    <mi>${numerator}</mi>
    <mi>${denominator}</mi>
  </mfrac>
`(key)

console.log(mfrac.namespaceURI) // "http://www.w3.org/1998/Math/MathML"

Nested Templates with Mixed Content

Partial svg and mathml templates (without <svg> or <math> root elements) can be nested inside html templates to produce properly namespaced mixed content:

const key = Symbol()
const centerX = 50
const centerY = 50
const radius = 40
const fillColor = 'lightblue'
const label = 'Dynamic SVG'
const variable = 'x'
const exponent = 2

const colors = ['deepink', 'gold', 'teal']

const [article] = html`
  <article>
    <h1>Mixed Content Example</h1>

    <section class="graphics">
      <svg width="100" height="100">
        ${colors.map(
          (color, i) =>
            svg`
              <circle cx=${centerX + i * 10} cy=${centerY + i * 10} r=${radius + i} fill=${color}/>
              <text x=${centerX + 5 + i} y=${centerY + 5 + i} text-anchor="middle" fill=${color}>${color}</text>
            `,
        )}
      </svg>
    </section>

    <section class="math">
      <math>
        ${colors.map(
          (color, i) =>
            mathml`
              <mrow style="font-size: 1.5em; color: ${color}; translate: ${i * 40}px ${i * 40}px;">
                <msup>
                  <mi>${color}</mi>
                  <mn>${exponent}</mn>
                </msup>
                <mo>+</mo>
                <mn>1</mn>
                <mo>=</mo>
                <mn>0</mn>
              </mrow>
            `,
        )}
      </math>
    </section>
  </article>
`(key)

// All elements have correct types and namespaces
const circle = article.querySelector('circle')
console.log(circle instanceof SVGCircleElement) // true

const mrow = article.querySelector('mrow')
console.log(mrow.namespaceURI) // "http://www.w3.org/1998/Math/MathML"

Skipping Equality Checks

By default, nimble-html performs equality checks to avoid unnecessary DOM updates. If a value hasn't changed between renders, the DOM won't be updated. However, sometimes you need to force updates even when values are the same.

There are two ways to force updates: the lightsaber ! syntax , and the force() function .

The Lightsaber Syntax (recommended)

Prefix any attribute binding with a lightsaber (!) to force updates regardless of value equality:

import {html} from 'nimble-html'

const key = Symbol()
let value = 'same'
const clickHandler = () => console.log('clicked')

// Force updates with ! prefix
const template = () =>
  html`
    <!-- These will always update, even with the same value -->

    <!-- Regular attribute -->
    <div !class=${value}></div>

    <!-- Boolean attribute -->
    <input !?disabled=${true} />

    <!-- JS property -->
    <input !.value=${value} />

    <!-- Event handler -->
    <button !@click=${clickHandler}>Click</button>
  `(key)

const [div, input1, input2, button] = template() // First render
template() // Second render - all DOM values are updated again

The `force()` Function

Alternatively, namely for scenarios where the lightsaber ! syntax cannot be used due to static analysis tool limitations that may only understand Lit-based syntax, you can wrap any interpolated value with force() to achieve the same effect (while achieving compatibility with Lit-based tools):

import {html, force} from 'nimble-html'

const key = Symbol()
let value = 'same'

const template = () =>
  html`
    <!-- These will always update, even with the same value -->
    <div class=${force(value)}></div>
    <div>${force('text content')}</div>
    <input .value=${force(value)} />
  `(key)

template() // First render
template() // Second render - all DOM values are updated again

Note

Only force() can be used with text content interpolations, i.e. <p>${force(value)}</p>, as the lightsaber ! syntax only applies to element attributes, properties, and events.

When to Use Force

Force updates are useful for:

Performance-sensitive updates: For example when the value to set is an array, and we only need to change a subset of items in the array. In such cases, triggering reactivity without creating a new array reference can be much faster, especially with large arrays that contain primitive values as those values will otherwise be copied in memory if a new array is created, triggering unnecessary garbage collections. By using force(), we can avoid creating new array references with copied values while forcing an underlying element to re-process the array contents.
Stateful components: When the same value should trigger side effects. For example, triggering a sound any time a value is set, even if unchanged, so that hitting a button repeatedly triggers the sound.
Forcing DOM updates: For example triggering MutationObserver callbacks to re-run logic, or to reset state modified by external code.
Third-party integration: When external libraries need explicit updates for any reason.

Warning

Be careful with the force. Overusing it can lead to performance issues since it bypasses the built-in optimization of avoiding unnecessary DOM updates. Use it only when necessary.

Mixing Approaches

Combining both ! and force() for the same interpolation works, but is unnecessary:

const template = () =>
  html`
    <!-- Both ! and force() -->
    <div !class=${force('combined')}></div>
  `(key)

Isolation

The force update behavior is isolated to specific attributes - it doesn't affect other attributes in the same template:

const template = () => html` <div !class=${'always-updates'} title=${'normal-behavior'}></div> `(key)

// Only the 'class' attribute will force update
// The 'title' attribute will use normal equality checking

Making Higher-level Frameworks

It's really simple with this nimble html tag!

Tiny Custom Element "Framework" Example

This example is so small, it's not really a framework, but it shows how straightforward it is to build custom elements with declarative-reactive html templates:

class MyElement extends HTMLElement {
  static {
    customElements.define('my-element', this)
  }

  #value = 123

  get value() {
    return this.#value
  }
  set value(val) {
    this.#value = val
    // Re-running the template with same key updates existing DOM. How easy!
    this.template()
  }

  template() {
    return html` <div>Current value: ${this.value}</div> `(this) // Use 'this' as the key
  }

  constructor() {
    super()
    this.attachShadow({mode: 'open'})
    this.shadowRoot.append(...this.template())
  }
}

const key = Symbol()
const app = value => html`<my-element .value=${value}></my-element>`(key)

document.body.append(...app(123))

// Renders "Current value: 123"

app(456)

// Renders "Current value: 456"

API Reference

Template Tag Functions

`html(strings, ...values)(key)`

Creates HTML elements with the HTML namespace. This is the main template function for regular HTML content.

`svg(strings, ...values)(key)`

Creates SVG elements with the SVG namespace (http://www.w3.org/2000/svg). Use this for creating SVG content that needs to be properly recognized as SVG elements.

`mathml(strings, ...values)(key)`

Creates MathML elements with the MathML namespace (http://www.w3.org/1998/Math/MathML). Use this for creating mathematical notation that renders properly in browsers.

const htmlTemplate = html`<div>${value}</div>`
const svgTemplate = svg`<circle cx="50" cy="50" r="25"/>`
const mathTemplate = mathml`<mfrac><mi>a</mi><mi>b</mi></mfrac>`

Parameters (all functions):

strings: TemplateStringsArray - The template literal strings
values: Array of interpolation values
key: Any unique value used to identify the DOM instance

Returns:

Array of the template's top-level Nodes with proper namespace and element types.

Supported Interpolations (all functions):

Text content: ${value}
Attributes: attr=${value} or attr="${value}"
Boolean attributes: ?attr=${boolean}
Properties: .prop=${value} (case-sensitive)
Events: @event=${handler} (case-sensitive)

Utility Functions

`force(value)`

Wraps a value to force DOM updates even when the new value is equal to the previous value. This bypasses nimble-html's built-in equality checking optimization.

This function provides the same functionality as the lightsaber ! syntax prefix (e.g., !class=${value}), but in function form for scenarios where static analysis tools made for Lit cannot otherwise understand the ! syntax.

import {html, force} from 'nimble-html'

// Force update even with the same value
const template = html`<div class=${force(className)}></div>`
const template2 = html`<div>${force('same text')}</div>`
const template3 = html`<input .value=${force(inputValue)} />`

Parameters:

value: Any - The value to wrap for forced updates

Returns:

Object - A wrapped value that will always trigger DOM updates

Development

See CONTRIBUTING.md for development guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.github		.github
examples		examples
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierrc.cjs		.prettierrc.cjs
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
html.js		html.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

lume/nimble-html

Folders and files

Latest commit

History

Repository files navigation

nimble-html

At a glance

Features

A closer look

Examples

Installation

Key Concepts (pun intended)

Template Identity and Keying

Attribute Types

Case Sensitivity for Properties and Events

Get Multiple Elements

Whitespace Handling

Nested Templates

Event Handlers

SVG and MathML Support

Nested Templates with Mixed Content

Skipping Equality Checks

The Lightsaber Syntax (recommended)

The force() Function

When to Use Force

Mixing Approaches

Isolation

Making Higher-level Frameworks

Tiny Custom Element "Framework" Example

API Reference

Template Tag Functions

html(strings, ...values)(key)

svg(strings, ...values)(key)

mathml(strings, ...values)(key)

Utility Functions

force(value)

Development

License

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Contributors 2

Languages

The `force()` Function

`html(strings, ...values)(key)`

`svg(strings, ...values)(key)`

`mathml(strings, ...values)(key)`

`force(value)`

Packages