mizu.js

Lightweight HTML templating library for any-side rendering.

mizu.js is a TypeScript/JavaScript library designed to provide a simple and efficient way to create dynamic web pages without the need for a complex framework nor additional setup.

Ideal for fast prototyping, generating static HTML pages, and developers seeking to streamline their workflow without the need of setting up a fully-fledged environment.

✓ No build steps
✓ No configuration needed
✓ Any-side rendering
✓ Great for static site generation
✓ Highly customizable

🌊 Fun Fact: This very page is generated using mizu.js!

Examples

Here's a collection of examples showcasing the capabilities of mizu.js.

Content generation × mizu.js

<!-- Fetch content with HTTP -->
<section class="feed" %http="'/feed'" %response.json="articles = $content">
  <h1>Articles</h1>
  <!-- Generate content from parsed response -->
  <article *for="const { id, title, type, content } of articles" *id="id">
    <h2 *text="title"></h2>
    <pre *if="type === 'code'"><code *code[ts]="content"></code></pre>
    <div *else="type === 'image'"><img :src="content"></div>
    <div *else="" *markdown="content"></div>
  </article>
  <div *empty.not="" *text="`${${generated}} results`"></div>
  <div *empty="">No results</div>
</section>

<!-- Generate a table of content based on existing headings -->
<nav *toc[h1-h2]="'.feed'"></nav>

Custom components × mizu.js

<!-- Define components inside a <template> and declare <slot> tags -->
<template *custom-component="say-hello">
  <div *clean.spaces="">
    <span *text="{ fr: 'Bonjour' }[$attrs.lang] ?? 'Hello'"></span>,
    <slot name="username"></slot>
  </div>
</template>

<!-- Use your newly declared component! -->
<say-hello lang="fr">
  <span #username="" *text="username"></span>
</say-hello>

Forms × mizu.js

<!-- Setup form -->
<section *set="{ data: { food: '🍱', quantity: 0 } }">
  <form %@submit.post="'/order'" %header[x-foo]="'bar'" %body.json="data">
    <!-- Declare some inputs -->
    <input type="number" ::value="quantity" min="0">
    <select ::value="food">
      <option *for="['🍱', '🍣', '🍥', '🍙']" :value="$value"></option>
    </select>
    <!-- Configure some buttons -->
    <button type="submit" :disabled="!quantity" :class="{ ok: quantity }">Order!</button>
    <button type="reset" @click.prevent="data.quantity = 0">Reset</button>
  </form>
</section>

Why choose mizu.js?

Any-side rendering: Compatible with most JavaScript runtimes and browsers. Templates can be rendered server-side, client-side, or using a mixture of both.
Compatibility with NodeJS, Bun and browsers is intended, but mizu.js is currently only tested with Deno as part of its early development.
Straightforward: Simply include its <script> or import statement to get started. No configuration or build steps are required.
Intuitive: Rely on HTML attributes and vanilla JavaScript expressions, no need to learn a new syntax or language.
Customizable: Make your own build using our custom builder to select specific features and reduce the final build size according to your project's needs, and create your own directives easily through developer-friendly APIs.
Open-core: Released under the AGPLv3 License and freely available at github.com/lowlighter/mizu.
A minimum of $1 monthly sponsorship grants you the right to use it in non open-sourced projects.

Usage

mizu.js is currently in active early development.
If you encounter any issues, please report them at github.com/lowlighter/mizu/issues/new.

To utilize mizu.js, just include the following line in your HTML document:

<script type="module" href="https://mizu.sh/mizu.js">

Or to use it as a JavaScript module:

import * as Mizu from "@lowlighter/mizu"

Assets are hosted on Vercel but mizu.js is also available on , , and CDN services that distributes npm packages such as JSdelivr.

All published versions are available in the /v/ directory. By default, the main branch is served.

Preset builds

mizu.js provides preset builds for added convenience. If you need a specific set of features, you can also use the custom builder.

This section has not been documented yet.

Concepts

Directive

A directive is a HTML attribute that has a special syntax that tells mizu.js how to process an element. The full syntax of a directive is as follows:

<tag

*name

[tag]

.modifier

[value]

="expression"

*name Directive name

Its first character usually indicates the type of directive:

@ when it reacts to a dispatched Event.
: when it manipulates HTML attributes.
% when it performs HTTP and network requests.
# when it handles <slot> elements.
* in remaining cases.

[tag] Tag (optional)

Its effect depends on the directive, but it is usually treated as the directive's argument or as a way to differentiate between multiple directives with the same name.

.modifier Modifier(s) (optional)

Each directive can have one or more modifiers that alter its behavior, which is described in the directive's documentation. Multiple modifiers can be chained together.
A same modifier should be used at most once per directive, reusing it is considered undefined behavior.

[value] Modifier value (optional)

Modifiers usually accept a value that can be one of the following types:

boolean, defaults to true.
string, defaults to "" and is case-insensitive.
number, defaults to 0.
duration, defaults to 0ms (supported unit modifiers are ms, s and m).

Phase (priority)

Each directive is processed in a specific order, called a phase (or Priority).

Phase list

00 META
01 PREPROCESSING
11 CONTEXT
21 EXPAND
22 MORPHING
23 TOGGLE
31 HTTP_HEADER
32 HTTP_BODY
33 HTTP_REQUEST
34 HTTP_CONTENT
35 HTTP_INTERACTIVITY
41 CONTENT
49 CONTENT_CLEANING
51 ATTRIBUTE
52 ATTRIBUTE_MODEL_VALUE
59 ATTRIBUTE_CLEANING
61 INTERACTIVITY
71 DISPLAY
81 CUSTOM_ELEMENT
82 REFERENCE
89 CUSTOM_PROCESSING
99 POSTPROCESSING

Since each directive is associated with a specific phase, the order in which they are declared on an element is usually not important.

It is not possible to use several directives with the same phase on the same element, unless it is explicitly allowed by the directive in which case they will be marked with the Multiple badge.
Using conflicting directives on the same element is considered undefined behavior.

Expression (JavaScript)

Most directives require a non-empty HTML attribute value, which will be evaluated asynchronously (meaning await is allowed) in the context of the current element upon processing.

Directives with a default value will be marked with the Default badge.

Unless specified otherwise, any expression that results in a single value is allowed.
Expressions are usually not processed in any specific way, offering access to the full capabilities of the JavaScript engine including its potential risks.

Context

All expressions will be evaluated in a specific context, which contains all the declared variables.

Depending on how you are using mizu.js, these values may be defined through the API or with directives. The latter may also define special variables (prefixed by $) depending on current processing state.

mizu.js uses @libs/reactive to track changes in the context and trigger a re-render when necessary.

Directives

General

`*mizu`
Priority`1 — PREPROCESSING`

Enable mizu rendering for the element and its children.

<script src="https://mizu.sh/mizu.js"></script>
<main *mizu="">
  <!--...-->
</main>

Contextual

`*set="context"`
Priority`11 — CONTEXT`

Set a context for an element and its children.

<div *set="{ foo: 'bar' }">
  <!--<span *text="foo"></span>-->
</div>

`*ref="name"`
Priority`82 — REFERENCE`

Create a reference to the element for later use.

<div *ref="foo" data-text="bar">
  <!--<p *text="$refs.foo.dataset.text"></p>-->
</div>

Conditional

`*if="expression"`
Priority`23 — TOGGLE`

Conditionally render an element.

<div *if="true">
  <!--...-->
</div>

`*else="expression"`
Default`true` Priority`23 — TOGGLE`

Conditionally render an element after another *if or *else directive.

<div *if="false"></div>
<div *else="false"></div>
<div *else=""><!--...--></div>

`*show="expression"`
Priority`71 — DISPLAY`

Conditionally display an element.

<div *show="true">
  <!--...-->
</div>

Iterative

`*for="expression"`
Priority`21 — EXPAND`

Render an element for each iteration.

<!--<ul>-->
<li *for="let item of items"></li>
<!--</ul>-->

`*id="expression"`
Priority`0 — META`

Hint for *for directive to differentiate generated elements.

<!--<ol>-->
<li *for="const {id} of items" *id="id"></li>
<!--</ol>-->

`*empty`
Priority`23 — TOGGLE`

Conditionally render an element after a *for directive.

<article *for="const article of articles"></article>
<p *empty.not="" *text="`${$generated} results`"></p>
<p *empty=""><!-- No results.--></p>

Content

`*text="content"`
Default`this.innerHTML` Priority`41 — CONTENT`

Set element's textContent.

<p *text="'...'">
  <!--...-->
</p>

`*html="content"`
Default`''` Priority`41 — CONTENT`

Set element's innerHTML.

<template *html="'<p>...</p>'">
  <!--<p>...</p>-->
</template>

`*code="content"`
Default`this.textContent` Priority`41 — CONTENT`

Set element's content after performing syntax highlighting.

<code *code[ts]="'...'">
  <!--<span class="hljs-*">...</span>-->
</code>

`*markdown="content"`
Default`this.textContent` Priority`41 — CONTENT`

Set element's content after performing Markdown rendering.

<div *markdown="'*...*'">
  <!--<em>...</em>-->
</div>

`*toc="selector"`
Default`'main'` Priority`41 — CONTENT`

Create a table of contents from <h1>...<h6> found in specified selector.

<nav *toc="'main'">
  <!--<ul>...</ul>-->
</nav>

`*clean`
Priority`49 — CONTENT_CLEANING`

Clean up the element and its children from specified content.

<div *clean="">
  <!--...-->
</div>

Custom elements

`*custom-element="tagname"`
Priority`81 — CUSTOM_ELEMENT`

<template *custom-element="my-element">
  <ul><slot name="items"></slot></ul>
</template>

`#slot`
Priority`0 — META`

Specify target <slot> in an element defined by a *custom-element directive.

<my-element>
  <li #items=""><!--...---></li>
</my-element>

`*is="tagname"`
Priority`22 — MORPHING`

Set an element tagname.

<div *is="'section'">
  <!--...-->
</div>

Events

`@event="listener"`
Default`null` Multiple Priority`61 — INTERACTIVITY`

Listen for a dispatched Event.

<button @click="this.value = 'Clicked!'">
  <!--Not clicked yet.-->
</button>

Binding

`:attribute="value"`
Multiple Priority`51 — ATTRIBUTE`

Bind an element's attribute value.

<a :href="url">
  <!--...-->
</a>

`:class="value"`
Multiple Priority`51 — ATTRIBUTE`

Bind an element's class attribute.

<p :class="{ foo: true, bar: false }">
  <!--...-->
</p>

`:style="value"`
Multiple Priority`51 — ATTRIBUTE`

Bind an element's style attribute.

<p :style="{ color: 'salmon' }">
  <!--...-->
</p>

Modeling

`::value="model"`
Priority`52 — ATTRIBUTE_MODEL_VALUE`

Bind an <input>, <select> or <textarea> element's value attribute in a bi-directional manner.

<select ::value="foo">
  <!--<option>...</option>-->
</select>

HTTP

`%http="url"`
Priority`33 — HTTP_REQUEST`

Perform a fetch() call that can be handled by %response directives.

<div %http="https://example.com">
  <!--...-->
</div>

Set HTTP headers for a %http directive.

<div %header[x-foo]="'bar'">
  <!--...-->
</div>

`%body="content"`
Priority`32 — HTTP_BODY`

Set HTTP body for a %http directive.

<div %body.json="{foo:'bar'}">
  <!--...-->
</div>

`%response="expression"`
Default`null` Multiple Priority`34 — HTTP_CONTENT`

Reacts to a %http directive's Response.

<div %http="'https://example.com'" %response.html="">
  <!--...-->
</div>

`%@event="listener"`
Default`null` Multiple Priority`35 — HTTP_INTERACTIVITY`

Listen for a dispatched Event and re-evaluates %http directive before reacting to its Response.

<button %http="https://example.com" %@click.html="">
  <!--...-->
</button>

Processing

`*once`
Priority`99 — POSTPROCESSING`

Render an element once and skip subsequent updates.

<div *once="">
  <!--...-->
</div>

`*refresh="interval"`
Priority`99 — POSTPROCESSING`

Force an element to be processed again at a specified interval (in seconds).

<div *refresh="1.5">
  <!--<time *text="new Date()"></time>-->
</div>

`*eval="expression"`
Priority`89 — CUSTOM_PROCESSING`

Evaluate a JavaScript expression in the context of the element.

<div *eval="console.log('$data')">
  <!--...-->
</div>

`*skip`
Priority`1 — PREPROCESSING`

Prevent an element from being processed.

<div *skip="">
  <!--<p *text="foo"></p>-->
</div>

API

This section has not been documented yet.

Full API documentation is available at jsr.io/@mizu/mizu.

FAQ

This section has not been documented yet.