Regor API

Find the API by purpose, try it live, and inspect the code behind its behavior.

This section contains the function-level reference for Regor.

Use this page as an index, then open each API page for signature details and examples.

45 APIs8 categoriesLive examples

Start with an app and writable state. Then choose the APIs for derivation, observation, composition, and cleanup.

Try it live

Three ways to derive a valueLive API
100computed · seats × price
8computeRef · seats × 2
29computeMany · seats + price

Three read-only values, three ways to specify their dependencies.

import { computed, computeMany, computeRef, html, ref } from 'regor'

export function createDerived(interactive = false) {
  const seats = ref(4)
  const price = ref(25)
  return {
    interactive,
    seats,
    price,
    total: computed(() => seats() * price()),
    double: computeRef(seats, (value) => value * 2),
    combined: computeMany([seats, price], (count, cost) => count + cost),
  }
}

export const derivedTemplate = html` <div class="guide-demo">
  <div class="guide-filter">
    <label
      >Seats · {{ seats }}<input
        type="range"
        min="1"
        max="12"
        r-model.number="seats"
        :value="seats"
        :disabled="!interactive" /></label
    ><label
      >Price · {{ price }}<input
        type="range"
        min="10"
        max="50"
        step="5"
        r-model.number="price"
        :value="price"
        :disabled="!interactive"
    /></label>
  </div>
  <div class="guide-metrics">
    <div>
      <output class="api-derived-total">{{ total }}</output
      ><span>computed · seats × price</span>
    </div>
    <div><output>{{ double }}</output><span>computeRef · seats × 2</span></div>
    <div>
      <output>{{ combined }}</output><span>computeMany · seats + price</span>
    </div>
  </div>
  <p class="guide-hint">
    Three read-only values, three ways to specify their dependencies.
  </p>
</div>`
import { createApp, RegorConfig, useScope } from 'regor'
import { apiExamples } from './examples'

const element = document.getElementById('api-demo')
const name = element?.dataset.example
if (element && name && Object.hasOwn(apiExamples, name)) {
  const example = apiExamples[name as keyof typeof apiExamples]
  const scope = useScope<object>(() => example.create(true))
  const config =
    'config' in scope.context && scope.context.config instanceof RegorConfig
      ? scope.context.config
      : undefined
  createApp(scope, { element, template: example.template }, config)
}

Move either slider. The three read-only outputs use computed, computeRef, and computeMany.

App and Components

createApp

Mount a context on existing DOM or supply a template for a reactive island.

Explore createApp

defineComponent

Define a reusable template with a context factory, props, and slots.

Explore defineComponent

pval

Validate component inputs at runtime with composable type and shape validators.

Explore pval

toFragment

Build a DocumentFragment from a JSON template describing HTML or SVG.

Explore toFragment

toJsonTemplate

Convert DOM elements into JSON templates for inspection or later rendering.

Explore toJsonTemplate

RegorConfig

Configure an app’s directives, global context, interpolation, and validation policy.

Explore regorConfig

Reactivity

ref

Create writable state and recursively convert nested object and array fields to refs.

Explore ref

cref

Copy a structure before deep conversion so the original data remains unchanged.

Explore cref

sref

Hold shallow writable state and replace plain object values to notify bindings.

Explore sref

isRef

Check whether a value is a Regor reactive reference.

Explore isRef

isDeepRef

Check whether a value carries Regor’s deep-ref marker.

Explore isDeepRef

unref

Read one ref layer, or return a non-ref value unchanged.

Explore unref

pause

Pause automatic notifications from a ref while retaining its stored value.

Explore pause

resume

Resume a ref’s notification behavior after a pause.

Explore resume

trigger

Notify a ref’s observers explicitly, with optional recursive triggering.

Explore trigger

entangle

Link two writable refs in both directions and return a function to disconnect them.

Explore entangle

Computed and Effects

computed

Derive a read-only value by tracking the refs read during a computation.

Explore computed

computeRef

Derive a read-only result from one explicit source ref.

Explore computeRef

computeMany

Derive a read-only result from an explicit list of source refs.

Explore computeMany

watchEffect

Run an effect immediately, then rerun it when the refs it reads change.

Explore watchEffect

collectRefs

Run an action and return both its result and the refs collected during its reads.

Explore collectRefs

silence

Exclude an action’s ref reads from active dependency collection.

Explore silence

Observation and Batch

observe

Subscribe to one ref and stop the subscription with the returned function.

Explore observe

observeMany

Subscribe to multiple refs and receive their current values in one callback.

Explore observeMany

observerCount

Inspect how many observer callbacks are registered on a ref.

Explore observerCount

batch

Group synchronous ref writes and flush their notifications after the callback.

Explore batch

startBatch

Start a manual notification batch to be closed with endBatch.

Explore startBatch

endBatch

Close a manual batch and flush notifications when the outer batch ends.

Explore endBatch

Lifecycle and Scope

useScope

Create a context with owned effects and lifecycle cleanup.

Explore useScope

onMounted

Register setup that runs when its owning app or component mounts.

Explore onMounted

onUnmounted

Register cleanup for resources owned by an app, component, or scope.

Explore onUnmounted

ContextRegistry

Register context instances and resolve them by their runtime class.

Explore contextRegistry

Cleanup and Unbind

addUnbinder

Associate a cleanup callback with a DOM node’s binding lifetime.

Explore addUnbinder

getBindData

Access or initialize the binding metadata associated with a node.

Explore getBindData

removeNode

Remove a node and schedule cleanup of its bindings.

Explore removeNode

unbind

Stop a node’s bindings and descendant listeners while retaining the DOM.

Explore unbind

drainUnbind

Flush the pending unbind queue after nodes have been removed.

Explore drainUnbind

Utilities

flatten

Unwrap a nested reactive structure into plain values.

Explore flatten

markRaw

Mark an object so deep conversion keeps its identity and plain fields.

Explore markRaw

isRaw

Check whether an object has been marked to skip deep conversion.

Explore isRaw

persist

Associate a ref with a localStorage key and restore its saved value.

Explore persist

html

Assemble a template string with a JavaScript tagged template literal.

Explore html

raw

Use the html tag’s string-assembly behavior under its raw alias.

Explore raw

svg

Assemble an SVG template string with the same tag behavior as html.

Explore svg

Logging

warningHandler

Customize Regor’s warning handling and retain a way to restore the previous handler.

Explore warningHandler

Recommendation

Start with:

  1. createApp
  2. ref
  3. cref
  4. sref
  5. computed
  6. watchEffect