VanJS: Tutorial and API Reference

Entia non sunt multiplicanda praeter necessitatem
(The best solution is usually the one with the least unnecessary complexity)

-- Occam's Razor

In this tutorial, we will break down into 3 core functionalities VanJS supports: DOM composition / manipulation, State and State binding.

DOM Composition and Manipulation

Your first VanJS app: a simple Hello page

We will start this tutorial with a simple Hello page, with the code below:

const {a, div, li, p, ul} = van.tags

const Hello = () => div(
  p("👋Hello"),
  ul(
    li("🗺️World"),
    li(a({href: "https://vanjs.org/"}, "🍦VanJS")),
  ),
)

van.add(document.body, Hello())

Try on jsfiddle

The code should be self-explanatory if you have some familiarity with HTML. Unlike React, everything in the code above is just pure JavaScript, meaning that you are simply calling functions from van.js without any transpiling that converts your source code into another form. Reusable UI components built with VanJS can be pure vanilla JavaScript functions as well. Here we capitalize the first letter to follow React conventions.

Also unlike React, VanJS does not introduce an ad-hoc virtual DOM layer. All the tag functions above directly return the created DOM objects. e.g.: the function call p("👋Hello") simply creates an HTMLParagraphElement with 👋Hello as its innerText, meaning that you can directly interact with your created DOM nodes with native DOM APIs.

💡 Tip: If you are tired of adding all the tag function names manually in the importing line:

const {a, div, li, p, ul} = van.tags

we have built a VS Code extension with the command that can automatically import the tag function at the cursor. You can check out its GitHub repo for more details.

API reference: van.tags

van.tags is a top-level dynamic object in VanJS implemented with Proxy. van.tags.<name> gets you a function that creates an HTML element with tag name <name>. A common way of using van.tags is like the line below:

const {a, div, p} = van.tags

With the line, a, div, p are functions that create <a>, <div>, <p> HTML elements respectively.

We will use div function as an example, the API reference for div tag function is as below:

SVG and MathML Support

HTML elements with namespace URI can be created via van.tagsNS, a variant of van.tags that allows you to specify the namespaceURI of the created elements. Here is an example of composing the SVG DOM tree with van.tagsNS:

const {circle, path, svg} = van.tagsNS("http://www.w3.org/2000/svg")

const Smiley = () => svg({width: "16px", viewBox: "0 0 50 50"},
  circle({cx: "25", cy: "25", "r": "20", stroke: "black", "stroke-width": "2", fill: "yellow"}),
  circle({cx: "16", cy: "20", "r": "2", stroke: "black", "stroke-width": "2", fill: "black"}),
  circle({cx: "34", cy: "20", "r": "2", stroke: "black", "stroke-width": "2", fill: "black"}),
  path({"d": "M 15 30 Q 25 40, 35 30", stroke: "black", "stroke-width": "2", fill: "transparent"}),
)

van.add(document.body, Smiley())

Demo:

Try on jsfiddle

Similarly, math formulas can be created with MathML elements via van.tagsNS:

const {math, mi, mn, mo, mrow, msup} = van.tagsNS("http://www.w3.org/1998/Math/MathML")

const Euler = () => math(
  msup(mi("e"), mrow(mi("i"), mi("π"))), mo("+"), mn("1"), mo("="), mn("0"),
)

van.add(document.body, Euler())

Demo:

Try on jsfiddle

API reference: van.tagsNS

API reference: van.add

van.add function is similar to tag functions described above. Instead of creating a new HTML element with specified properties and children, van.add function mutates its first argument (which is an existing Element node) by appending 0 or more children with appendChild calls:

DOM nodes already in the document tree can't be used as children

As mentioned in the API reference, if a DOM node is already connected to the document tree, it shouldn't be used as the child node of tag function or van.add. The following code is invalid and an Error will be thrown when van-<version>.debug.js is being used:

const existing = document.getElementById("some-id")

// Invalid! Existing node can't be used as the child node of tag function.
const dom = div({id: "new-id"}, existing)

// Invalid! Existing node can't be appended to other nodes in `van.add`.
van.add(document.body, existing)

Functional-style DOM tree building

Because both tag functions and van.add can take Array arguments and the Array arguments can be deeply nested. VanJS enables very ergonomic DOM tree composition in functional-style. See examples below:

Building a bullet list:

const {li, ul} = van.tags

const List = ({items}) => ul(items.map(it => li(it)))

van.add(document.body, List({items: ["Item 1", "Item 2", "Item 3"]}))

Try on jsfiddle

Building a table:

const {table, tbody, thead, td, th, tr} = van.tags

const Table = ({head, data}) => table(
  head ? thead(tr(head.map(h => th(h)))) : [],
  tbody(data.map(row => tr(
    row.map(col => td(col)),
  ))),
)

van.add(document.body, Table({
  head: ["ID", "Name", "Country"],
  data: [
    [1, "John Doe", "US"],
    [2, "Jane Smith", "CA"],
    [3, "Bob Johnson", "AU"],
  ],
}))

Try on jsfiddle

on... event handlers

In tag functions, you can provide a function value for property keys like on.... This is a convenient way to specify event handlers. For instance, the code below creates a button that shows an alert whenever clicked:

button({onclick: () => alert("Hello from 🍦VanJS")}, "Hello")

Try on jsfiddle

🎉 Congratulations! You have mastered the skills for building and manipulating DOM trees using VanJS's declarative API, which is incredibly powerful for creating comprehensive applications with elegant code. In the sections below, you will continue to learn how to build reactive applications with state and state binding.

If your application doesn't rely on state and state binding, you can use the slimmed-down version of VanJS - Mini-Van.

State

A State object in VanJS represents a value that can be updated throughout your application. A State object has a public property val, with a custom setter that automatically propagates changes to DOM nodes that are bound to it.

The code below illustrates how a State object can be used:

const {button, div, input, sup} = van.tags

// Create a new state object with init value 1
const counter = van.state(1)

// Log whenever the value of the state is updated
van.derive(() => console.log(`Counter: ${counter.val}`))

// Derived state
const counterSquared = van.derive(() => counter.val * counter.val)

// Used as a child node
const dom1 = div(counter)

// Used as a property
const dom2 = input({type: "number", value: counter, disabled: true})

// Used in a state-derived property
const dom3 = div({style: () => `font-size: ${counter.val}em;`}, "Text")

// Used in a state-derived child
const dom4 = div(counter, sup(2), () => ` = ${counterSquared.val}`)

// Button to increment the value of the state
const incrementBtn = button({onclick: () => ++counter.val}, "Increment")
const resetBtn = button({onclick: () => counter.val = 1}, "Reset")

van.add(document.body, incrementBtn, resetBtn, dom1, dom2, dom3, dom4)

Demo:

Try on jsfiddle

API reference: van.state

Public interface of State objects

• Property val - the current value of the State object. When a new value of this property is set, all derived states and side effects registered via van.derive and all DOM nodes that are bound to it will be updated accordingly.
• Readonly property oldVal - the old value of the State object prior to the current UI update cycle. This property might be useful for stateful binding.

The value of a State object can be almost anything, primitive, Object, Array, null, etc., with 2 ad-hoc exceptions that we made: The value of the State object cannot be a DOM node, or another State object. Having values in these 2 types carries little semantic information and is more likely a result of coding bugs. Thus we disallow State objects to have values in these 2 types. In van-{version}.debug.js, an explicit error will be thrown if you try to assign a DOM node or another State object as the value of a state.

See also: Why can't states have DOM node as values?

State.val is immutable

While you can update State objects by setting the val property, you should never mutate the underlying object of val itself. Doing so will not trigger the DOM tree update as you would expect and might result in undefined behavior due to aliasing. In van-<version>.debug.js, attempt to mutate the object in val will lead to an Error to be thrown.

Derived state

Derived states can be declared via van.derive, as illustrated in the example below:

const {input, span} = van.tags

const DerivedState = () => {
  const text = van.state("VanJS")
  const length = van.derive(() => text.val.length)
  return span(
    "The length of ",
    input({type: "text", value: text, oninput: e => text.val = e.target.value}),
    " is ", length, ".",
  )
}

van.add(document.body, DerivedState())

Demo:

Try on jsfiddle

API reference: van.derive

Side effect

van.derive can be used to declare side effects as well. You can discard the return value of van.derive if you are not interested. The code below is a modified Counter App which logs the counter to console whenever it changes:

const {button, span} = van.tags

const Counter = () => {
  const counter = van.state(0)
  van.derive(() => console.log("Counter: ", counter.val))
  return span(
    "❤️ ", counter, " ",
    button({onclick: () => ++counter.val}, "👍"),
    button({onclick: () => --counter.val}, "👎"),
  )
}

van.add(document.body, Counter())

Try on jsfiddle

See also: Advanced state derivation

State Binding

Once State objects are created, we can bind them to DOM nodes in various ways to make your UI reactive to state changes.

State objects as properties

State objects can be used as properties of HTML elements. Similar to State-based child nodes, the value of the properties will be always in sync with the value of the respective states. When State objects are used as properties, you need to make sure that the values of the states are always valid property values, i.e.: primitives or functions (for event handlers).

The following code demonstrates 2 text inputs whose values are always in sync:

const {input, span} = van.tags

const ConnectedProps = () => {
  const text = van.state("")
  return span(
    input({type: "text", value: text, oninput: e => text.val = e.target.value}),
    input({type: "text", value: text, oninput: e => text.val = e.target.value}),
  )
}

van.add(document.body, ConnectedProps())

Demo:

Try on jsfiddle

State objects as child nodes

State objects can be used as child nodes in tag functions and van.add, like the Counter example shown in the home page. For a State object used as a child node, its value needs to be primitive (string, number, boolean or bigint), and a Text node will be created for it. The content of the created Text node will be always in sync with the value of the state.

The following code shows how to build a simple timer with this feature:

const {button, span} = van.tags

const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))

const Timer = ({totalSecs}) => {
  const secs = van.state(totalSecs)
  return span(
    secs, "s ",
    button({onclick: async () => {
      while (secs.val > 0) await sleep(1000), --secs.val
      await sleep(10) // Wait briefly for DOM update
      alert("⏰: Time is up")
      secs.val = totalSecs
    }}, "Start"),
  )
}

van.add(document.body, Timer({totalSecs: 5}))

Demo:

Try on jsfiddle

State-derived properties

State-derived property is a more advanced way to bind a property of an HTML element to one or more underlying State objects. To declare a State-derived property, you need to provide a function as the value in props argument while calling to a tag function. The function takes no parameter and return the value of the property. Whenever any dependency of the function changes, the value of the property will be updated accordingly.

The example below is a live font size and color preview implemented with this feature:

const {input, option, select, span} = van.tags

const FontPreview = () => {
  const size = van.state(16), color = van.state("black")
  return span(
    "Size: ",
    input({type: "range", min: 10, max: 36, value: size,
      oninput: e => size.val = e.target.value}),
    " Color: ",
    select({oninput: e => color.val = e.target.value, value: color},
      ["black", "blue", "green", "red", "brown"]
        .map(c => option({value: c}, c)),
    ),
    // The <span> element below has a state-derived property `style`
    span({style: () => `font-size: ${size.val}px; color: ${color.val};`}, " Hello 🍦VanJS"),
  )
}

van.add(document.body, FontPreview())

Demo:

Try on jsfiddle

van._(...) to escape on... event handlers

When declaring a State-derived property for an on... event handler, you should wrap around the binding function with van._(...). Otherwise, the function you provide will be consider as the event handler, rather than the binding function for the State-derived property. See the example below:

const {button, option, select, span} = van.tags

const Counter = () => {
  const counter = van.state(0)
  const action = van.state("👍")
  return span(
    "❤️ ", counter, " ",
    select({oninput: e => action.val = e.target.value, value: action},
      option({value: "👍"}, "👍"), option({value: "👎"}, "👎"),
    ), " ",
    button({onclick: van._(() => action.val === "👍" ?
      () => ++counter.val : () => --counter.val)}, "Run"),
  )
}

van.add(document.body, Counter())

Demo:

Try on jsfiddle

State-derived child nodes

Similarly, you can bind an HTML node to one or more underlying State objects. To declare a State-derived child node, you need to provide a function as the child argument while calling to a tag function or van.add. The function you provide can return a primitive value (a Text node will be created for it) or a DOM node. The following example illustrates this:

const {input, li, option, select, span, ul} = van.tags

const SortedList = () => {
  const items = van.state("a,b,c"), sortedBy = van.state("Ascending")
  return span(
    "Comma-separated list: ",
    input({oninput: e => items.val = e.target.value,
      type: "text", value: items}), " ",
    select({oninput: e => sortedBy.val = e.target.value, value: sortedBy},
      option({value: "Ascending"}, "Ascending"),
      option({value: "Descending"}, "Descending"),
    ),
    // A State-derived child node
    () => sortedBy.val === "Ascending" ?
      ul(items.val.split(",").sort().map(i => li(i))) :
      ul(items.val.split(",").sort().reverse().map(i => li(i))),
  )
}

van.add(document.body, SortedList())

Demo:

Try on jsfiddle

Removing a DOM node

For State-derived child nodes, if the binding function returns null or undefined, the DOM node will removed. Removed DOM node will never be brought back, even when the binding function would return a non-null/undefined value based on future values of the dependencies.

The following code illustrates how to build an editable list with this features:

const {a, button, div, input, li, ul} = van.tags

const ListItem = ({text}) => {
  const deleted = van.state(false)
  return () => deleted.val ? null : li(
    text, a({onclick: () => deleted.val = true}, "❌"),
  )
}

const EditableList = () => {
  const listDom = ul()
  const textDom = input({type: "text"})
  return div(
    textDom, " ",
    button({onclick: () => van.add(listDom, ListItem({text: textDom.value}))}, "➕"),
    listDom,
  )
}

van.add(document.body, EditableList())

Demo:

Try on jsfiddle

Stateful binding

While dealing with state updates for State-derived child node, a user can choose to, instead of regenerating the new version of the DOM node entirely based on new state values, mutate the existing DOM node that is already connected to the document tree based on all the new values and old values of its dependencies. This feature can be used as an optimization to avoid the entire DOM subtree being completely re-rendered.

The following code is a snippet of the auto-complete application which leverages this feature to optimize:

div({class: "root"}, textarea({onkeydown, oninput}), dom => {
  if (dom && candidates.val === candidates.oldVal) {
    // If the candidate list doesn't change, we don't need to re-render the
    // suggetion list. Just need to change the selected candidate.
    dom.querySelector(`[data-index="${selectedIndex.oldVal}"]`)
      ?.classList?.remove("selected")
    dom.querySelector(`[data-index="${selectedIndex.val}"]`)
      ?.classList?.add("selected")
    return dom
  }
  return SuggestionList({candidates: candidates.val, selectedIndex: selectedIndex.val})
})

The piece of code above is building a suggestion list that is reactive to the changes of selection candidates and selectedIndex. When selection candidates change, the suggestionList needs to be regenerated. However, if only selectedIndex changes, we only need to update the DOM element to indicate that the new candidate is being selected now, which can be achieved by changing the classList of relevant candidate elements.

To facilitate stateful binding, the binding function takes the dom parameter, which is the current version of the DOM node prior to UI updates (or undefined when the binding function is first called). The binding function can either return dom (which means we don't want to update the DOM node to a new version), a primitive value (a new Text node will be created for it), or a new DOM node (whose isConnected property should be false).

Polymorphic Binding

If you use VanJS to build reusable UI components, it's desirable for your components to accept both state and non-state property values. For instance, for a reusable button component like that:

const Button = ({color, ...}) = button(
  ...
)

it would be desirable for button to accept both static color value and color state. If the color property is used as a DOM node property or as a child node, things can work out of the box, as tag functions and van.add support both state and non-state values in props and children parameter. However, if the color property is used as a State-derived property or a State-derived child, it would be hard for your component to work in both ways. Consider the example below:

button({style: () => `background-color: ${color};`},
  ...
)

When color is a static value, we should use ${color}. However, when color is a state, we should use ${color.val} instead. This makes it hard to build reusable UI component that accepts both state and non-state property values. VanJS has 2 helper functions: van.val and van.oldVal to help you in this situation:

API reference: van.val

API reference: van.oldVal

A practical example

Now, let's take a look at a practical example - a reuseable button whose color, text and onclick properties can be either state or non-state objects:

const {button, span} = van.tags

const Button = ({color, text, onclick}) =>
  button({style: () => `background-color: ${van.val(color)};`, onclick}, text)

const App = () => {
  const colorState = van.state("green")
  const textState = van.state("Turn Red")

  const turnRed = () => {
    colorState.val = "red"
    textState.val = "Turn Green"
    onclickState.val = turnGreen
  }
  const turnGreen = () => {
    colorState.val = "green"
    textState.val = "Turn Red"
    onclickState.val = turnRed
  }
  const onclickState = van.state(turnRed)

  return span(
    Button({color: "yellow", text: "Click Me", onclick: () => alert("Clicked")}), " ",
    Button({color: colorState, text: textState, onclick: onclickState}),
  )
}

van.add(document.body, App())

Demo:

Try on jsfiddle

The End

🎉 Congratulations! You have completed the entire tutorial of VanJS. Now you can start your journey of building feature-rich applications!

To learn more, you can:

• check out a list of sample applications built with VanJS.
• read the in-depth discussion of a few advanced topics.
• check out how to build a fullstack app with SSR, CSR and hydration.

API Index

Below is the list of all top-level APIs in VanJS:

• van.tags
• van.tagsNS
• van.add
• van.state
• van.derive
• van._
• van.val
• van.oldVal
• van.hydrate