useComputed • tldraw Docs

Creates a new computed signal with custom options for advanced behavior like custom equality checking, diff computation, and history tracking. The computed signal will be created only once.

function useComputed<Value, Diff = unknown>(
  name: string,
  compute: () => Value,
  opts: ComputedOptions<Value, Diff>,
  deps: any[]
): Computed<Value>

Example

function ShoppingCart() {
  const items = useAtom('items', [])

  // Computed with custom equality to avoid recalculation for equivalent arrays
  const sortedItems = useComputed(
    'sortedItems',
    () => items.get().sort((a, b) => a.name.localeCompare(b.name)),
    {
      isEqual: (a, b) =>
        a.length === b.length && a.every((item, i) => item.id === b[i].id),
    },
    [items]
  )

  return <ItemList items={sortedItems.get()} />
}

Parameters

Name	Description
`name`	`string` A descriptive name for the computed signal, used for debugging and identification
`compute`	`() => Value` A function that computes the value, automatically tracking any signal dependencies
`opts`	`ComputedOptions<Value, Diff>` Configuration options for the computed signal isEqual - Custom equality function to determine if the computed value has changed computeDiff - Function to compute diffs between old and new values for history tracking historyLength - Maximum number of diffs to keep in history buffer for time-travel functionality
`deps`	`any[]` React dependency array that controls when the computed signal is recreated

Returns

Computed<Value>

A computed signal containing the calculated value with the specified options