Features

Features are top-level constructs that define the behavior of an element. Every hyperscript program is made up of one or more features. They handle events, define functions, manage state, and set up reactive bindings.

name description example
on Creates an event listener on click log "clicked!"
def Defines a function see details...
init Initialization logic to be run when the code is first loaded
set Defines a new element-scoped variable
behavior Define cross-cutting behaviors that are applied to many HTML elements
install Install a behavior onto the current element install Draggable
js Embed JavaScript code at the top level see details...
live Declare reactive commands that re-run when dependencies change live set $total to ($price * $qty)
when React to value changes with side effects, async, or events when $x changes ...
bind Two-way sync between values with element auto-detection bind $name to me

Extensions

These features are available via extension scripts:

name description example
eventsource Subscribe to Server Sent Events (SSE)
socket Create a Web Socket
worker Create a Web Worker for asynchronous work

Commands

Commands are the executable statements of hyperscript. They are the actions that run inside features - putting values, adding classes, fetching data, controlling flow, and more. Commands can be chained with then and most support an implicit me target.

See also pseudo-commands.

name description example
add Adds content to a given target add .myClass to me
append Appends a value to a string, array or HTML Element append "value" to myString
beep Debug printing beep! <.foo/>
break Breaks out of the current loop repeat 3 times break end
call/get Evaluates an expression (e.g. a Javascript Function) call alert('yep, you can call javascript!')

get prompt('Enter your name')
continue Skips the remainder of a loop and continues at the top of the next iteration. repeat 3 times continue end
decrement Subtracts a value from a variable, property, or attribute decrement counter
default Sets a variable to a value if it is currently undefined default x to 0
empty Removes all child nodes from an element empty #results
exit Exits the current handler without returning a value if x is null exit
focus Focuses an element focus #search-input
blur Removes focus from an element blur me
fetch Send a fetch request fetch /demo then put it into my.innerHTML
go Navigate to a URL go to /about, go back
scroll Scroll an element into view scroll to the top of #section smoothly
halt Halts the current event (stopping propagate, etc.) halt
hide Hide an element in the DOM hide me
if A conditional control flow command if I match .selected then call alert('I\'m selected!')
increment Adds a value to a variable, property, or attribute increment counter
js Embeds javascript js alert('this is javascript'); end
log Logs a given expression to the console, if possible log me
make Creates a class instance or DOM element make a Set from a, b. c, make a <p/> called para
measure Gets the measurements for a given element measure me then log it
pick Selects items from arrays, strings and regex match results pick first 3 of arr, pick match of "(\w+)" of str
put Puts a value into a given variable or property put "cool!" into me
remove Removes content log "bye, bye" then remove me
repeat Iterates repeat for x in [1, 2, 3] log x end
return Returns a value return 42
send/trigger Sends an event send customEvent to #a-div
set Sets a variable or property to a given value set x to 0
settle Waits for a transition to end on an element, if any add .fade-out then settle
show Show an element in the DOM show #anotherDiv
take Takes a class from a set of elements take .active from .tabs
tell Temporarily sets a new implicit target value tell <p/> add .highlight
throw Throws an exception throw "Bad Value"
toggle Toggles content on a target toggle .clicked on me
transition Transitions properties on an element transition my *opacity to 0
wait Waits for an event or a given amount of time before resuming the command list wait 2s then remove me
open Opens dialogs, details, popovers, or enters fullscreen open #my-dialog, open fullscreen
close Closes dialogs, details, popovers, or exits fullscreen close #my-dialog, close fullscreen
select Selects text in an input or textarea select #search-input
ask Shows a browser prompt dialog, result in it ask "Your name?"
answer Shows an alert or confirm dialog answer "Save?" with "Yes" or "No"
speak Text-to-speech via the Web Speech API speak "Hello" with rate 2
breakpoint Pauses execution in the browser DevTools breakpoint

Expressions

Expressions are the values and references that commands operate on. They include DOM selectors, property access, comparisons, math, and type conversions. Hyperscript expressions are designed to read naturally and work seamlessly with the DOM.

See expressions for an overview.

DOM References

name description example
id reference An element ID reference #main-div
class reference A CSS class reference .active
query reference A CSS query selector <button/> <:focused/>
attribute reference An element attribute reference @selected
style reference An element style reference *color *computed-fontSize
closest expression Find closest ancestor matching a selector closest <div/>
relative positional Navigate to relative elements next <div/> from me
positional expressions Get a positional value from a set first from <div/>

Property Access

name description example
of expression Get a property of an object the location of window
possessive expressions Possessive property access the window's location
property access Dot notation property access event.target
array index Bracket notation access items[0] obj['key']
cookies symbol A symbol for accessing cookies cookies['My-Cookie']

Operators

name description example
math operator Arithmetic operators (mod replaces %) x + 1 y * 2 z mod 3
comparison operator Comparison and type-checking operators x == "foo" I match <:active/>
logical operator Logical operators x and y not z a or false
no operator Emptiness/existence check no element.children
some operator Existence check (inverse of no) some <.results/>
as expression Converts an expression to a new type "10" as Int
pipe operator Chain conversions left to right x as Values | JSONString
in expression Containment check "foo" in myArray
starts with / ends with String prefix/suffix check url starts with "https"
is between Inclusive range check x is between 1 and 10
precedes / follows DOM document-order check #a precedes #b
ignoring case Case-insensitive modifier for comparisons x contains "hi" ignoring case

Collection Expressions

name description example
where Filter a collection items where its active
sorted by Sort a collection items sorted by its name descending
mapped to Map/project a collection items mapped to its id
split by Split a string into an array "a,b" split by ","
joined by Join an array into a string items joined by ", "

Literals

name description example
string String literals with template interpolation "Hello ${name}"
time expression A time expression 200ms 2s
CSS units Numeric values with CSS unit suffixes 10px 2em 50%
block literal Anonymous functions with an expression body \ x -> x * x

Debugging

name description example
beep! Debug expression that logs and passes through beep! <.foo/>

Magic Values

Magic values are special names that are automatically available in hyperscript contexts. They provide access to the current element, event information, and previous results without explicit declaration.

Element References

name description example
me Reference to the current element (aliases: my, I) put 'clicked' into me
you Reference to a target element set by tell tell <p/> remove yourself
body Reference to document.body put "Hello" into body
clipboard System clipboard (async read, sync write) put clipboard into me, set clipboard to "hi"
selection Currently selected text put selection into #out

Result Values

name description example
it The result of a previous command (aliases: its, result) fetch /people as json then put it into people

Event Context

These are available inside event handlers (e.g. on click):

name description example
event The current event object log event.type
target The target of the current event (event.target) add .clicked to target
detail The detail of a custom event (event.detail) log detail.message
sender The element that sent a custom event (event.detail.sender) log sender.id

Literals

Literals are inline values in your code. Hyperscript supports the same literal types as JavaScript, so you can write values naturally.

name description example
arrays Javascript-style array literals [1, 2, 3]
booleans Javascript-style booleans true false
null Javascript-style null null
numbers Javascript-style numbers 1 3.14
objects Javascript-style object literals {foo:"bar", doh:42}
strings String literals with template interpolation "a string" 'another string'

Events

Hyperscript dispatches these events during its lifecycle. You can listen for them with standard addEventListener or hyperscript's on feature.

Lifecycle

name description
hyperscript:ready Triggered on the document after hyperscript has processed the page
load Triggered on an element with hyperscript on it after it has loaded
hyperscript:before:init Triggered on an element before its hyperscript is initialized
hyperscript:after:init Triggered on an element after its hyperscript is initialized
hyperscript:before:cleanup Triggered on an element before its hyperscript is cleaned up
hyperscript:after:cleanup Triggered on an element after its hyperscript is cleaned up

Fetch

name description
fetch:beforeRequest Triggered before a fetch command sends a request
fetch:afterResponse Triggered after a fetch command receives a response
fetch:afterRequest Triggered after a fetch command handles a response
fetch:error Triggered when a fetch command gets an error
fetch:abort Triggered when a fetch command request is aborted

Errors

name description
hyperscript:parse-error Triggered when parse errors are found (detail contains errors array)
exception Triggered when a runtime error occurs (detail contains error)

Debugging

name description
hyperscript:beep Triggered when a beep! command executes