Valtio

Valtio v2 introduced several breaking changes and environment requirements:

• React Version: Requires React 18 or above.
• TypeScript Version: Requires TypeScript 4.5 or above.
• Build Target: Updated to ES2018.
• useSnapshot() Behavior: The implementation was altered to improve compatibility with useMemo and the React compiler. This may result in extra re-renders in certain edge cases.
• Deprecated Features: All previously deprecated features have been removed.

When using objects as keys in a proxyMap, Valtio's proxying mechanism might interfere with key equality. To ensure a key remains exactly what you intended (preserving its identity), wrap the key object with ref.

• With ref: The key is treated as a stable reference, allowing state.get(key) to work correctly.
• Without ref: The key is proxied, which can cause state.get(key) to return undefined because the proxy object does not match the original key used in .set().

import { proxyMap, ref } from 'valtio/utils'

// Use ref to preserve key identity
const key = ref({})
state.set(key, 'hello')
state.get(key) // 'hello'

// Without ref, the key is proxied and equality fails
const key2 = {}
state.set(key2, 'value')
state.get(key2) // undefined

If you prefer not to use useRef to manage the lifecycle of a proxy within a component, you can consider the following alternatives:

• use-constant: A utility to keep a value constant across renders.
• bunshi: A dependency injection library that provides recipes for Valtio.
• Custom Hooks: Create your own hooks that wrap useContext and optionally useSnapshot to provide a cleaner API for consuming component-scoped state.

While most serializable objects and classes can be proxied, certain special objects cannot be tracked effectively. Changes to these objects will not trigger updates in the Valtio state.

Unsupported types (will not trigger updates):

• DOM elements (e.g., d3.select('#chart'))
• React elements (e.g., React.createElement('div'))
• Certain built-in collections like Map (use proxyMap instead)
• Browser APIs like localStorage

Supported types:

• Serializable objects
• Class instances

// This works
class User {
  first = null
  last = null
  constructor(first, last) {
    this.first = first
    this.last = last
  }
  greet() {
    return `Hi ${this.first}!`
  }
}

const state = proxy(new User('Timo', 'Kivinen'))

If you prefer not to use useRef to manage the lifecycle of a scoped Valtio proxy, you can use the following alternatives:

• use-constant: A utility to keep a value constant across renders.
• Bunshi: A dependency injection library that has specific recipes for Valtio.
• Custom Hooks: Create a custom hook that combines useContext and useSnapshot to simplify consumption in child components.

By default, the subscribe callback only provides access to the current state. However, you can enable Ops (Operations) to receive detailed records of exactly what changed (e.g., which property was set, updated, or deleted).

This is useful for implementing advanced features like:

• State synchronization across different environments
• Undo/redo functionality

Note: Tracking operations incurs a small performance cost, so they are disabled by default. You must explicitly enable them to access the Ops argument in the callback.

Proxies can be nested inside other proxy objects. When a nested proxy is updated, the parent proxy tracks the change, allowing you to update deep properties through the parent reference.

import { proxy } from 'valtio'

const personState = proxy({ name: 'Timo', role: 'admin' })
const authState = proxy({ status: 'loggedIn', user: personState })

// Updating the nested proxy via the parent
authState.user.name = 'Nina'

Valtio includes built-in optimizations to prevent unnecessary re-renders and updates:

1. Noop (No-operation): If you set a property to the exact same value it currently holds, the update is ignored and subscribers are not notified.
2. Batching: Multiple mutations occurring within the same event loop tick are batched together. Subscribers will only be notified once for the entire batch of changes.

const state = proxy({ count: 0, text: 'hello' })

// Noop: setting to the same value has no effect
state.count = 0 

// Batching: subscribers are notified once after both mutations
state.count = 1
state.text = 'world'

const state = proxy({ count: 0, text: 'hello' })

// noop
state.count = 0 

// batching
state.count = 1
state.text = 'world'

Valtio allows you to create circular references within your proxy state. While this is a specialized use case, you can assign a proxy (or a part of it) to one of its own properties.

const state = proxy({
  obj: { foo: 3 },
})

// Create a circular reference
state.obj.bar = state.obj