Legend-State Documentation

When using the <For> component in React, you can pass the optimized prop to improve performance. If the each prop is an observable object record (e.g., Record<string, T>), setting optimized ensures that the component correctly reacts to key membership changes, such as inserting new keys or deleting existing ones.

Previously, optimized object records might not have re-rendered when keys were added or removed; with the current implementation, <For each={record$} optimized> will correctly update when record keys are inserted, deleted, or replaced by a same-size key set, while still suppressing unnecessary renders for nested field updates.

You can install Legend-State using bun, npm, or yarn.

bun add @legendapp/state
# or
npm install @legendapp/state
# or
yarn add @legendapp/state

When using Object.values() on an Observable<Record<string, T>> to create a derived list, Legend-State ensures that deleting items from the source record correctly updates the derived array.

Previously, deleting a non-tail item in a record could leave stale activated array index children. Now, when a record-backed computed array shrinks, trailing child nodes are removed, and deleted children are fully deactivated to ensure that shifted indexes and out-of-range reads correctly reflect the current state of the array.

When using syncedCrud with arrays, performing an immutable root replacement (e.g., using .set() on the entire array) can cause unsynced records to be lost if a previous create operation failed. This happens because multiple logical operations might share the same root path (e.g., pending['']), and a successful operation could prematurely clear the pending state for the entire path.

Workaround: Instead of replacing the entire array immutably, mutate the array using .push(). This avoids the root-path collision by targeting specific indices rather than the root path.

If you need to reset or clear an observable (e.g., setting it to undefined) inside an onChange listener or any other logic where you want to avoid triggering a second change notification/cleanup loop, use the setSilently function.

While calling .delete() on an observable is intentionally observable (it triggers listeners with undefined), setSilently acts as an escape hatch to update the value without notifying any listeners.

import { setSilently } from '@legendapp/state';

// Clears the observable without triggering any listeners
setSilently(observable$, undefined);

To prevent an entire React component from re-rendering when a value changes, use the <Memo> component. This allows only the specific part of the UI to update, leaving the rest of the component untouched.

import { useObservable } from "@legendapp/state/react"
import { Memo } from "@legendapp/state/react"

function FineGrained() {
    const count$ = useObservable(0)

    // Example interval updating the state
    useInterval(() => {
        count$.set(v => v + 1)
    }, 600)

    // The text updates itself so the component doesn't re-render
    return (
        <div>
            Count: <Memo>{count$}</Memo>
        </div>
    )
}

Use observable() to create state. You can access raw data using .get() and update it using .set(). You can also create computed observables by passing a function to observable() that tracks other observables.

import { observable, observe } from "@legendapp/state"

const settings$ = observable({ theme: 'dark' })

// get returns the raw data
settings$.theme.get() // 'dark'

// set sets the value
settings$.theme.set('light')

// Computed observables with just a function
const isDark$ = observable(() => settings$.theme.get() === 'dark')

// observing contexts re-run when tracked observables change
observe(() => {
  console.log(settings$.theme.get())
})

To use Legend-State in React, wrap your component with observer from @legendapp/state/react. Inside the component, calling .get() on an observable will cause the component to re-render whenever that specific value changes.

import { observable } from "@legendapp/state"
import { observer } from "@legendapp/state/react"

const settings$ = observable({ theme: 'dark' })

const Component = observer(function Component() {
    const theme = settings$.theme.get()

    return <div>Theme: {theme}</div>
})