DOM tree microhydration
Sprae is open & minimalistic progressive enhancement framework.
Perfect for small-scale websites, static pages, landings, prototypes, or lightweight UI.
A light alternative to alpine, petit-vue etc.
<div id="container" :if="user">
Hello <span :text="user.name">World</span>.
</div>
<script type="module">
import sprae from 'sprae'
// init
const state = sprae(container, { user: { name: 'Kitty' } })
// update
state.user.name = 'Dolly'
</script>Sprae evaluates :-directives and evaporates them, returning reactive state for updates.
Control flow of elements.
<span :if="foo">foo</span>
<span :else :if="bar">bar</span>
<span :else>baz</span>
<!-- fragment -->
<template :if="foo">foo <span>bar</span> baz</template>Multiply element.
<ul><li :each="item in items" :text="item"/></ul>
<!-- cases -->
<li :each="item, idx in array" />
<li :each="value, key in object" />
<li :each="count, idx in number" />
<!-- fragment -->
<template :each="item in items">
<dt :text="item.term"/>
<dd :text="item.definition"/>
</template>Set text content of an element.
Welcome, <span :text="user.name">Guest</span>.
<!-- fragment -->
Welcome, <template :text="user.name" />.Set class value.
<!-- appends class -->
<div class="foo" :class="bar"></div>
<!-- array/object, a-la clsx -->
<div :class="[foo && 'foo', {bar: bar}]"></div>Set style value.
<!-- extends style -->
<div style="foo: bar" :style="'baz: qux'">
<!-- object -->
<div :style="{foo: 'bar'}"></div>
<!-- CSS variable -->
<div :style="{'--baz': qux}"></div>Set value of an input, textarea or select.
<input :value="value" />
<textarea :value="value" />
<!-- selects right option & handles selected attr -->
<select :value="selected">
<option :each="i in 5" :value="i" :text="i"></option>
</select>
<!-- handles checked attr -->
<input type="checkbox" :value="checked" />Set any attribute(s).
<label :for="name" :text="name" />
<!-- multiple attributes -->
<input :id:name="name" />
<!-- spread attributes -->
<input :="{ id: name, name, type: 'text', value }" />Define values for a subtree.
<x :with="{ foo: 'bar' }">
<y :with="{ baz: 'qux' }" :text="foo + baz"></y>
</x>Expose element with name.
<textarea :ref="text" placeholder="Enter text..."></textarea>
<!-- iterable items -->
<li :each="item in items" :ref="item">
<input :onfocus..onblur="e => (item.classList.add('editing'), e => item.classList.remove('editing'))"/>
</li>Run effect, not changing any attribute.
<div :fx="a.value ? foo() : bar()" />
<!-- cleanup function -->
<div :fx="id = setInterval(tick, interval), () => clearInterval(tick)" />Attach event(s) listener with optional modifiers.
<input type="checkbox" :onchange="e => isChecked = e.target.value">
<!-- multiple events -->
<input :value="text" :oninput:onchange="e => text = e.target.value">
<!-- sequence of events -->
<button :onfocus..onblur="e => ( handleFocus(), e => handleBlur())">
<!-- modifiers -->
<button :onclick.throttle-500="handler">Not too often</button>.once,.passive,.capture– listener options..prevent,.stop(.immediate) – prevent default or stop (immediate) propagation..window,.document,.outside,.self– specify event target..throttle-<ms>,.debounce-<ms>– defer function call with one of the methods..<key>– filtered byevent.key:.ctrl,.shift,.alt,.meta,.enter,.esc,.tab,.space– direct key.delete– delete or backspace.arrow– up, right, down or left arrow.digit– 0-9.letter– A-Z, a-z or any unicode letter.char– any non-space character.ctrl-<key>, .alt-<key>, .meta-<key>, .shift-<key>– key combinations, eg..ctrl-alt-deleteor.meta-x.
.*– any other modifier has no effect, but allows binding multiple handlers to same event (like jQuery event classes).
Include as
import 'sprae/directive/data'.
Set data-* attributes. CamelCase is converted to dash-case.
<input :data="{foo: 1, barBaz: true}" />
<!-- <input data-foo="1" data-bar-baz /> -->Include as
import 'sprae/directive/aria'.
Set aria-* attributes. Boolean values are stringified.
<input role="combobox" :aria="{
controls: 'joketypes',
autocomplete: 'list',
expanded: false,
activeOption: 'item1',
activedescendant: ''
}" />
<!--
<input role="combobox" aria-controls="joketypes" aria-autocomplete="list" aria-expanded="false" aria-active-option="item1" aria-activedescendant>
-->Include as
import 'sprae/directive/html'.
Set html content of an element or instantiate a template.
Hello, <span :html="userElement">Guest</span>.
<!-- fragment -->
Hello, <template :html="user.name">Guest</template>.
<!-- instantiate template -->
<template :ref="tpl"><span :text="foo"></span></template>
<div :html="tpl" :with="{foo:'bar'}">...inserted here...</div>Sprae uses signals for reactivity and can take signal values as inputs. Signals provider can be switched to any preact-flavored implementation:
import sprae from 'sprae';
import { signal, computed, effect, batch, untracked } from 'sprae/signal';
import * as signals from '@preact/signals-core';
// switch provider to @preact/signals-core
sprae.use(signals);
// use signal as state value
const name = signal('Kitty')
sprae(el, { name });
// update state
name.value = 'Dolly';| Provider | Size | Feature |
|---|---|---|
ulive (default) |
350b | Minimal implementation, basic performance, good for small states. |
@webreflection/signal |
531b | Class-based, better performance, good for small-medium states. |
usignal |
850b | Class-based with optimizations, good for medium states. |
@preact/signals-core |
1.47kb | Best performance, good for any states, industry standard. |
signal-polyfill |
2.5kb | Proposal signals. Use via adapter. |
Properties prefixed with _ indicate untracked value:
let state = sprae(el, {x:1, _y:2})
state.x++ // updates template
state._y++ // no side-effectExpressions use new Function as default evaluator, which is fast & compact way, but violates "unsafe-eval" CSP. To make eval stricter & safer, as well as sandbox expressions, an alternative evaluator can be used, eg. justin:
import sprae from 'sprae'
import justin from 'subscript/justin'
sprae.use({compile: justin}) // set up justin as default compilerJustin is minimal JS subset that avoids "unsafe-eval" CSP and provides sandboxing.
++ -- ! - + ** * / % && || ??
= < <= > >= == != === !==
<< >> & ^ | ~ ?: . ?. [] ()=>{} in
[] {} "" ''
1 2.34 -5e6 0x7a
true false null undefined NaN
Sprae can be tailored to project needs via sprae/core:
// sprae.custom.js
import sprae, { directive } from 'sprae/core'
import { effect } from 'sprae/signal'
import * as signals from '@preact/signals'
import compile from 'subscript'
// standard directives
import 'sprae/directive/default.js'
import 'sprae/directive/if.js'
import 'sprae/directive/text.js'
// custom directive :id="expression"
directive.id = (el, evaluate, state) => {
effect(() => el.id = evaluate(state))
}
// configure signals
sprae.use(signals)
// configure compiler
sprae.use({ compile })- To prevent FOUC add
<style>[:each],[:if],[:else] {visibility: hidden}</style> - Attributes order matters, eg.
<li :each="el in els" :text="el.name"></li>is not the same as<li :text="el.name" :each="el in els"></li> - To destroy state and detach sprae handlers, call
element[Symbol.dispose](). - State getters/setters work as computed effects, eg.
sprae(el, { x:1, get x2(){ return this.x * 2} }). thiskeyword is not used, to get access to current element use<input :ref="el" :text="el.value"/>- Async/await is not supported in attributes, it's a strong indicator you need to put these methods into state.
- Template-parts is stuck with native HTML quirks (parsing table, SVG attributes, liquid syntax conflict etc).
- Alpine / petite-vue / lucia escape native HTML quirks, but have excessive API (
:,x-,{},@,$), tend to self-encapsulate and not care about size/performance.
Sprae holds open, sweet & minimalistic philosophy:
- Slim
:API and signals reactivity. - Pluggable directives & configurable internals.
- Small, safe & performant.
- Bits of organic sugar.
- Aims at making developers happy 🫰