State

Something that is truly missing in web APIs is reactivity, the ability to react to changes instead of listening to events. A big promise is the tc39 proposal which is attempting to bring signals to JavaScript.

Until then, Markup exposes a standalone API that gives you that capability called state.

The state API can be used with or without templates allowing you to create state stores, enhance Web Components, and even provide reactivity with raw DOM manipulation.

javascript
                const [count, setCount] = state(0)

const btn = document.createElement('button')
btn.type = 'button'

btn.addEventListener('click', () => {
    setCount((prev) => prev + 1)
})

effect(() => {
    btn.textContent = `count: ${count()}`
})

document.body.append(btn)
            

The best part is when you combine state and templates to render DOM nodes that react to updates as they happen without having to manipulate the DOM yourself.

javascript
                const handleClick = () => {
    setCount((prev) => prev + 1)
}

html`<button type="button" onclick="${handleClick}">count: ${count}</button>`
            

Markup templates do not traverse the DOM to check for updates. Instead, it creates render effects in place to update the DOM exactly where and when needed.

Input

To initialize a state, you can optionally provide an initialValue as well as a StateSubscriber which is a function that will be called every time the state changes.

typescript
                const [count] = state<number>(0, () => {
    // react to change
})
            

When no input value provided, the default value is an empty string.

Return

The state function will return and array with three functions, a StateGetter, StateSetter, and a StateUnSubscriber.

javascript
                const [count, updateCount, unsubscribe] = state(0, () => {
    // will only get called once
})

updateCount(10)

unsubscribe()
            

StateGetter

The StateGetter is a function you must call to get the current value of the state.

javascript
                const [count] = state(0)

console.log(count()) // logs 0
            

StateSetter

The StateSetter is a function you call with the new value for the state or a function that gets called with the current value and must return a new value.

javascript
                const [count, updateCount] = state(0)

// provide a new value
updateCount(10)

// use current value and perform a calculation
updateCount(count() + 5)

// use the callback to update the value
updateCount((prev) => prev + 5)
            

Calling the StateSetter with same value will not cause the subscribers to be called. A shallow comparison is made before updating the current value which prevents unnecessary updates.

javascript
                const [count, updateCount] = state(0, () => {
    // this will never get called
    // given the setInterval update bellow
    console.log(count())
})

setInterval(() => {
    updateCount(0)
}, 1000)
            

StateUnSubscriber

In case you provide a StateSubscriber as a second argument for the state, you can then use the StateUnSubscriber to stop listening to the state changes.

javascript
                const [count, updateCount, unsubscribeFromCount] = state(0, () => {
    // react to change
})

unsubscribeFromCount()
            

How it works?

The state is a synchronous value which means you can update it in one line and read it on the next.

javascript
                setCount(10)
console.log(count()) // logs 10
            

Behind the scenes, state is just a self managed subscription that works seamlessly with effect and html APIs.

Examples

Form input value and validation:

javascript
                const [valid, setValid] = state(true)
const [value, setValue] = state('', () => {
    if (value().length > 8) {
        setValid(false)
    }

    setValid(true)
})
            

edit this doc