trigger

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

triggerReactivity

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

Overview

The trigger function is used to manually trigger observers and update dependent refs. This function is particularly useful when you need to manually control when ref updates and observer notifications occur.

Try it live

Separate stored values from notificationsLive API

Live preview

0Stored value

0Observer's last value

0Callbacks

Notifications are active.

Pause, write, then resume and trigger. The stored value and the last observed value show different responsibilities.

notifications.ts

import { html, observe, pause, ref, resume, trigger } from 'regor'

export function createNotifications(interactive = false) {
  const source = ref(0),
    stored = ref(0),
    seen = ref(0),
    callbacks = ref(0),
    paused = ref(false)
  observe(source, (value) => {
    seen(value)
    callbacks(callbacks() + 1)
  })
  return {
    interactive,
    stored,
    seen,
    callbacks,
    paused,
    write: () => {
      source(source() + 1)
      stored(source())
    },
    pauseSource: () => {
      pause(source)
      paused(true)
    },
    resumeSource: () => {
      resume(source)
      paused(false)
    },
    notify: () => trigger(source),
  }
}

export const notificationsTemplate = html` <div class="guide-demo">
  <div class="guide-session-bar">
    <button type="button" @click="write" :disabled="!interactive">
      Write +1</button
    ><button
      type="button"
      @click="pauseSource"
      :disabled="!interactive || paused"
    >
      Pause</button
    ><button
      type="button"
      @click="resumeSource"
      :disabled="!interactive || !paused"
    >
      Resume</button
    ><button type="button" @click="notify" :disabled="!interactive || paused">
      Trigger
    </button>
  </div>
  <div class="guide-metrics">
    <div><output>{{ stored }}</output><span>Stored value</span></div>
    <div><output>{{ seen }}</output><span>Observer's last value</span></div>
    <div><output>{{ callbacks }}</output><span>Callbacks</span></div>
  </div>
  <p class="guide-event">
    Notifications are {{ paused ? 'paused' : 'active' }}.
  </p>
  <p class="guide-hint">
    Pause, write, then resume and trigger. The stored value and the last
    observed value show different responsibilities.
  </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)
}

Pause, write, resume, and trigger. Compare the stored value with what the observer last received.

Usage

Manually Triggering Observers

To manually trigger observers for a specific ref, call the trigger function with the ref as the source argument. This will notify all observers of the ref and update any dependent refs.

import { trigger, ref, observe } from 'regor'

const myRef = ref(5)

observe(myRef, () => {
  console.log('Observer triggered:', myRef.value)
})

myRef.value = 10 // The observer is automatically triggered

// Manually trigger the observer
trigger(myRef)

// Outputs:
// Observer triggered: 10

Recursive Triggering

By default, the trigger function only notifies observers of the specified ref. If you want to trigger observers recursively for nested refs within arrays, sets, maps, or objects, you can set the isRecursive argument to true. This will trigger observers for all nested refs.

import { trigger, ref, observe } from 'regor'

const myRef = ref([1, 2, 3])

observe(myRef, () => {
  console.log('Observer triggered:', myRef.value)
})

myRef.value.push(4) // The observer is automatically triggered

// Manually trigger the observer recursively
trigger(myRef, undefined, true)

// Outputs:
// Observer triggered: [1, 2, 3, 4]

Parameters

source: The ref for which you want to manually trigger observers.
eventSource (optional): An optional event source that can be provided to identify the source of the trigger. This can be useful for debugging and tracking trigger events.
isRecursive (optional): A boolean flag that, when set to true, triggers observers recursively for nested refs within arrays, sets, maps, and objects. By default, this is set to false.

Manual notification is an explicit choice

Use trigger when a change needs notification beyond the normal setter behavior. Keep recursive triggering scoped to the data that needs it.

Notes

The trigger function is typically used for advanced scenarios where manual control over observer notifications is required. In most cases, observers are automatically notified when a ref's value changes.
Recursive triggering can be resource-intensive if there are deep and complex nested structures. Use it judiciously to avoid unnecessary performance overhead.