computeRef

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

computeRefComputed and Effects

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

Overview

The computeRef function allows you to create a computed ref object that automatically computes its value based on a source ref object and a computation function. This is useful for deriving values from reactive data and ensuring that the computed ref updates whenever the source ref changes.

Try it live

Three ways to derive a valueLive API

Live preview

Seats · 4Price · 25

100computed · seats × price

8computeRef · seats × 2

29computeMany · seats + price

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

derived.ts

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>`

browser.ts

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.

Usage

Creating Computed Refs

To create a computed ref using computeRef, you provide a source ref and a computation function. The computation function calculates the computed value based on the value of the source ref, and the computed ref will automatically update when the source ref changes.

import { computeRef, ref } from 'regor'

const myRef = ref(5)

// Create a computed ref
const computedValue = computeRef(myRef, (value) => value * 2)

console.log(computedValue.value) // Outputs 10

// Later, when myRef changes, computedValue will automatically update
myRef.value = 7
console.log(computedValue.value) // Outputs 14

Parameters

source: The source ref object that the computed ref depends on. Changes to the source ref will trigger the computation.
compute: A function that calculates the computed value based on the current value of the source ref. This function should not have side effects and should only depend on reactive data.

Return Value

The computeRef function returns a computed ref object that holds the computed value. You can access the computed value using the .value property of the computed ref or by invoking it directly.

Example

import { computeRef, ref } from 'regor'

const myRef = ref(5)

// Create a computed ref
const computedValue = computeRef(myRef, (value) => value * 2)

console.log(computedValue.value) // Outputs 10

// Later, when myRef changes, computedValue will automatically update
myRef.value = 7
console.log(computedValue.value) // Outputs 14

One source, one transformation

Choose computeRef when the input dependency should be stated directly rather than discovered through reads.