Lightweight HTML templating library for any-side rendering.
mizu.js is a JavaScript library that provides a simple and efficient way to create dynamic web pages without the complexity of a fully-fledged framework or additional setup.
Ideal for rapid prototyping, generating static HTML pages, and developers seeking to wok in a hassle-free environment.
🌊 Fun Fact: This very page is generated using mizu.js!
Here's a collection of examples showcasing the capabilities of 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><!-- 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><!-- 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><script> or import statement to get started. No configuration or build steps are required.
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.
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.
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:
*name Directive name@ when it reacts to a dispatched Event.
: when it manipulates HTML attributes.
% when it performs HTTP and network requests.
# when it handles <slot> elements.
~ when intended for testing and debugging purposes.
* in remaining cases.[tag] Tag (optional).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).
Each directive is processed in a specific order, called a phase (or Priority).
00
META
01
ELIGIBILITY
02
PREPROCESSING
10
TESTING
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.
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.
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.
*mizu
1 — ELIGIBILITY
Enable mizu rendering for the element and its children.
<main *mizu="">
<!--...-->
</main>*set="context"
11 — CONTEXT
Set a context for an element and its children.
<div *set="{ foo: 'bar' }">
<!--<span *text="foo"></span>-->
</div>*ref="name"
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>*if="expression"
23 — TOGGLE
Conditionally render an element.
<div *if="true">
<!--...-->
</div>*else="expression"
true
Priority23 — TOGGLE
Conditionally render an element after another *if or *else directive.
<div *if="false"></div>
<div *else="false"></div>
<div *else=""><!--...--></div>*show="expression"
71 — DISPLAY
Conditionally display an element.
<div *show="true">
<!--...-->
</div>*for="expression"
21 — EXPAND
Render an element for each iteration.
<!--<ul>-->
<li *for="let item of items"></li>
<!--</ul>-->*id="expression"
0 — META
Hint for *for directive to differentiate generated elements.
<!--<ol>-->
<li *for="const {id} of items" *id="id"></li>
<!--</ol>-->*empty
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>*text="content"
this.innerHTML
Priority41 — CONTENT
Set element's textContent.
<p *text="'...'">
<!--...-->
</p>*html="content"
41 — CONTENT
Set element's innerHTML.
<template *html="'<p>...</p>'">
<!--<p>...</p>-->
</template>*mustache
41 — CONTENT
Enable content interpolation between mustaches
({{ and }}) from Text child nodes.
<p *mustache="">
<!--{{ ... }}-->
</p>*code="content"
this.textContent
Priority41 — CONTENT
Set element's content after performing syntax highlighting.
<code *code[ts]="'...'">
<!--<span class="hljs-*">...</span>-->
</code>*markdown="content"
this.textContent
Priority41 — CONTENT
Set element's content after performing markdown rendering.
<div *markdown="'*...*'">
<!--<em>...</em>-->
</div>*toc="selector"
'main'
Priority41 — CONTENT
Create a table of contents from <h1>...<h6> found in specified selector.
<nav *toc="'main'">
<!--<ul>...</ul>-->
</nav>*clean
49 — CONTENT_CLEANING
Clean up the element and its children from specified content.
<div *clean="">
<!--...-->
</div>*custom-element="tagname"
81 — CUSTOM_ELEMENT
Register a new custom element.
<template *custom-element="my-element">
<ul><slot name="items"></slot></ul>
</template>#
0 — META
Specify target <slot> in an element defined by a *custom-element directive.
<my-element>
<li #items=""><!--...---></li>
</my-element>*is="tagname"
22 — MORPHING
Set an element tagname.
<div *is="'section'">
<!--...-->
</div>@="listener"
null
Multiple
Priority61 — INTERACTIVITY
Listen for a dispatched Event.
<button @click="this.value = 'Clicked!'">
<!--Not clicked yet.-->
</button>:="value"
51 — ATTRIBUTE
Bind an element's attribute value.
<a :href="url">
<!--...-->
</a>:class="value"
51 — ATTRIBUTE
Bind an element's class attribute.
<p :class="{ foo: true, bar: false }">
<!--...-->
</p>:style="value"
51 — ATTRIBUTE
Bind an element's style attribute.
<p :style="{ color: 'salmon' }">
<!--...-->
</p>::="model"
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="url"
33 — HTTP_REQUEST
Perform a fetch() call that can be handled by %response directives.
<div %http="https://example.com">
<!--...-->
</div>%header[]="value"
31 — HTTP_HEADER
Set HTTP headers for a %http directive.
<div %header[x-foo]="'bar'">
<!--...-->
</div>%body="content"
32 — HTTP_BODY
Set HTTP body for a %http directive.
<div %body.json="{foo:'bar'}">
<!--...-->
</div>%response="expression"
null
Multiple
Priority34 — HTTP_CONTENT
Reacts to a %http directive's Response.
<div %http="'https://example.com'" %response.html="">
<!--...-->
</div>%@="listener"
null
Multiple
Priority35 — 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>*once
99 — POSTPROCESSING
Render an element once and skip subsequent updates.
<div *once="">
<!--...-->
</div>*refresh="interval"
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"
89 — CUSTOM_PROCESSING
Evaluate a JavaScript expression in the context of the element.
<div *eval="console.log('$data')">
<!--...-->
</div>*skip
2 — PREPROCESSING
Prevent an element from being processed.
<div *skip="">
<!--<p *text="foo"></p>-->
</div>~test="expression"
10 — TESTING
Special directive for testing purposes.
<samp ~test[testing].text="'...'">
<!--...-->
</samp>This section has not been documented yet.
Full API documentation is available at jsr.io/@mizu/mizu.
This section has not been documented yet.