///_hyperscript

Documentation

Quick Start

Load hyperscript and start it:

<script src="https://unpkg.com/hyperscript.org@0.0.1-alpha2"></script>
<script>
_hyperscript.start();
</script>

Then add some hyperscript to an element:

<div _="on click call alert('You clicked me!')">
  Click Me!
</div>

Introduction

hyperscript is a small, expressive scripting language designed to embed well directly in HTML (thus satisfying the Locality of Behaviour Principle). It is a companion project of htmx and the two integrate automatically when used together.

hyperscript is inspired by the HyperTalk programming language and has a distinct english-like syntax, with native event-handling syntax. hyperscript transpiles to ES5.1 and thus is compatible with all modern browsers, as well as IE11.

Yet Another Language?

I know.

The initial motivation for the language was the event model in htmx. I wanted to have a way to utilize these events naturally and directly within HTML. Most HTML tags support on* attributes for handling standard DOM events (e.g. onClick) but that doesn't work for custom events. In intercooler, I had handled this by adding a bunch of custom event attributes, but that always felt hacky and wasn't general enough to handle custom events triggered by response headers, etc.

Additionally, I wanted to have a way to address some useful features from intercooler.js, but without causing htmx to lose focus on the core request/response processing infrastructure:

The more I looked at it, the more I thought that there was a need for a small, domain specific language for all this, rather than an explosion in attributes and inline javascript, or a hacky custom syntax as with ic-action.

The Language

So, what does hyperscript look like?

As mentioned above, hyperscript is designed to embed well directly within HTML:

<button _="on click add .clicked">
  Add The "clicked" Class To Me
</button>

The underscore (_) attribute is where hyperscript is stored. You can also use script or data-script attribute, or configure a different attribute if you don't like those.

The script above says

On the 'click' event for this button, add the 'clicked' class to the button

The syntax reads a lot like the english does. This is intentional and drawn from HyperTalk (and its successors, such as AppleTalk)

You can extend this example to target another element like so:

<div id="a-div">I'm a div</div>
<button _="on click add .clicked to #a-div">
  Add The "clicked" Class To That Div Above Me
</button>

Now the clicked class will be added to the div with the id a-div, rather than to the element the event handler is on.

You can see in the example above that hyperscript has native syntactic support for CSS class literals as well as well as ID references. This makes it easy to express common DOM manipulations without a lot of unnecessary syntax.

The Basics

Now that you've seen a basic introduction, let's look at the broader language.

A hyperscript consists of one or more features. Currently, the only feature supported right now is the on feature, which instantiates an event listener on the current DOM element.

A feature then contains a series of commands, a term taken from HyperTalk. A more standard name would be "statements", but calling them "commands" is fun. A command typically consists of a starting keyword (which makes parsing easy!) and then a series of keywords and expressions.

A command list is a series of commands, optionally separated by the then keyword:

<div _="on click add .fadeMe then wait 200ms then remove me">
  Fade & Remove Me
</div>

The then keyword is particularly recommended when commands are on the same line, for clarity.

Some commands, such as the if command contain lists of other commands as well.

Expressions are the root syntactic element. Some should be very familiar to developers:

While some are a bit more exotic for an imperative programming language:

Below is a reference for the various features, commands and expressions available in hyperscript:

Features

name description example
on Creates an event listener on click log "clicked!"

Commands

name description example
add Adds content to a given target add .myClass to me
ajax Send an AJAX request ajax GET /demo then put response into my.innerHTML
call/get Evaluates an expression (e.g. a Javascript Function) call alert('yep, you can call javascript!)

get prompt('Enter your name')
if A conditional control flow command if me.selected then call alert('I\'m selected!')
log Logs a given expression to the console, if possible log me
put Puts a value into a given variable or property put "cool!" into me.innerHTML
remove Removes content log "bye, bye" then remove me
send Sends an event send customEvent to #a-div
set Sets a variable or property to a given value set x to 0
take Takes a class from a set of elements take .active from .tabs
toggle Toggles content on a target toggle .clicked on me
trigger triggers an event on the current element trigger customEvent
wait Waits a given amount of time before resuming the command list wait 2s then remove me

Expressions

name description example
array literal An array literal, as in JavaScript [1, 2, 3]
attribute reference An attribute reference [selected=true]
block literal An anonymous function with an expression body \ x -> x * x
boolean Boolean literals true
false
class reference A class reference .active
comparison oeprator Comparison operators x < y
z === "foo"
id reference A class reference #main-div
logical oeprator Logical operators x and y
z or false
math operator A mathematical operator 1 + 2
number A number 3.14
object literal A javascript-style object literal {foo:"bar"}
string A string "a string", 'another string'
target A target for update .buttons.parent