ref

A ref allows unproxied state in a Valtio proxy

A ref is useful in the rare instances you need to nest an object in a proxy that is not wrapped in an inner proxy and, therefore, is not tracked.

const store = proxy({
    users: [
        { id: 1, name: 'Juho', uploads: ref([]) },
    ]
  })
})

Once an object is wrapped in a ref, it should be mutated without reassigning the object or rewrapping in a new ref.

// ✅ do mutate
store.users[0].uploads.push({ id: 1, name: 'Juho' })
// ✅ do reset
store.users[0].uploads.splice(0)

// ❌ don't reassign
store.users[0].uploads = []

A ref should also not be used as the only state in a proxy, making the proxy usage pointless.

Using ref with an existing Valtio proxy

ref can also be used with a proxy that has already been created. This is useful when a child proxy is managed independently and should not propagate its updates through a parent proxy.

const child = proxy({ count: 0 })
const parent = proxy({ child: ref(child) })

When passed an existing Valtio proxy, ref returns the same object rather than creating a wrapper:

ref(child) === child // true

The child proxy is not tracked by the parent, so changes to child do not notify subscribers of parent. The child is also kept by identity in the parent snapshot rather than being replaced with an immutable child snapshot:

snapshot(parent).child === child // true

The marking applies to the proxy's identity globally within the current Valtio runtime; it is not scoped to the parent.child property. If the same proxy is later placed in another parent without calling ref again, that parent also treats the child as an untracked reference:

const anotherParent = proxy({ child })
// Changes to child do not notify anotherParent either.

Subscribe to the child proxy separately when you need to observe its updates:

subscribe(child, () => {
  // child changed
})

Use ref(existingProxy) deliberately, because it affects how that proxy identity participates in later proxy composition.

Codesandbox demo

Error embedding https://codesandbox.io/s/valtio-file-load-demo-oo2yzn?codemirror=1&fontsize=14&hidenavigation=1&theme=light&hidedevtools=1.