markRaw

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

markRawUtilities

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

Overview

The markRaw function allows you to mark a given value as "raw," indicating that it should not be converted into a deep ref when using the ref function. Marking a value as "raw" ensures that specific nested properties or the entire object will remain untracked and not reactive.

Try it live

A deliberate conversion boundaryLive API

Live preview

Reactive field

The marked resource keeps its identity and its plain fields during deep conversion.

CONVERSION BOUNDARY

isRaw(resource): true
Same resource object: true
isRef(resource.label): false
Reactive title: Reactive title

raw-state.ts

import { computed, html, isRaw, isRef, markRaw, ref } from 'regor'

export function createRawState(interactive = false) {
  const resource = markRaw({ label: 'External resource' })
  const state = ref({ resource, title: 'Reactive title' })
  return {
    interactive,
    state,
    rawCheck: isRaw(resource),
    sameObject: state().resource === resource,
    nestedIsRef: isRef(resource.label),
    snapshot: computed(() => state().title()),
  }
}

export const rawStateTemplate = html` <div class="guide-demo guide-demo--split">
  <div class="guide-controls">
    <label for="raw-title">Reactive field</label
    ><input
      id="raw-title"
      type="text"
      maxlength="50"
      r-model="state.title"
      :value="snapshot"
      :disabled="!interactive"
    />
    <p class="guide-hint">
      The marked resource keeps its identity and its plain fields during deep
      conversion.
    </p>
  </div>
  <div class="guide-readout">
    <span class="guide-kicker">CONVERSION BOUNDARY</span>
    <dl class="directive-values">
      <div>
        <dt>isRaw(resource)</dt>
        <dd>{{ rawCheck }}</dd>
      </div>
      <div>
        <dt>Same resource object</dt>
        <dd>{{ sameObject }}</dd>
      </div>
      <div>
        <dt>isRef(resource.label)</dt>
        <dd>{{ nestedIsRef }}</dd>
      </div>
      <div>
        <dt>Reactive title</dt>
        <dd>{{ snapshot }}</dd>
      </div>
    </dl>
  </div>
</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)
}

Edit the reactive title. The marked resource keeps its object identity and plain nested field.

Usage

Marking a Value as Raw

To mark a value as raw, you can use the markRaw function.

import { markRaw } from 'regor'

const myValue = /* Your object here */

// Marking the object as raw
const rawValue = markRaw(myValue)

Parameters

value: The object or value you want to mark as raw, preventing it from being deeply converted into a ref object.

Return Value

The markRaw function returns the same value that you passed as an argument, but with an additional marker indicating it is a raw value.

Implementation Details

The function sets a marker on the provided value using the rawSymbol to indicate that it should not be deeply converted into a ref.
The marked object remains untracked when used with the ref function.

Example

import { markRaw, ref } from 'regor'

const data = {
  name: 'Alice',
  age: 30,
  rawProperty: markRaw({ nested: 'value' }),
}

const myRef = ref(data)

// Changes to rawProperty will not trigger reactivity
myRef().rawProperty.nested = 'updated value'
console.log(myRef().rawProperty.nested) // Outputs 'updated value'

Mark before deep conversion

Use markRaw for an object that should remain outside deep conversion, such as a resource owned by another library.