or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-proxy.mdindex.mdreact-integration.mdutilities.md
tile.json

tessl/npm-valtio

Proxy-state management library that makes state simple for React and vanilla JavaScript applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/valtio@2.1.x

To install, run

npx @tessl/cli install tessl/npm-valtio@2.1.0

index.mddocs/

Valtio

Valtio makes proxy-state simple for React and vanilla JavaScript applications. It creates self-aware proxy objects that automatically track mutations and trigger re-renders only when accessed parts of the state change, offering maximum simplicity and performance with minimal boilerplate.

Package Information

  • Package Name: valtio
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install valtio

Core Imports

import { proxy, useSnapshot } from "valtio";

For vanilla JavaScript or utilities:

import { proxy, snapshot, subscribe, ref, getVersion } from "valtio";
import { watch, subscribeKey, devtools, deepClone, proxySet, proxyMap, isProxySet, isProxyMap } from "valtio/utils";

CommonJS:

const { proxy, useSnapshot } = require("valtio");
const { watch, subscribeKey, devtools, deepClone, proxySet, proxyMap } = require("valtio/utils");

Basic Usage

import { proxy, useSnapshot } from "valtio";

// Create reactive state
const state = proxy({ count: 0, text: "hello" });

// React component with automatic re-renders
function Counter() {
  const snap = useSnapshot(state);
  return (
    <div>
      {snap.count}
      <button onClick={() => ++state.count}>+1</button>
    </div>
  );
}

// Vanilla JavaScript with subscriptions
import { snapshot, subscribe } from "valtio";

const unsubscribe = subscribe(state, () => {
  console.log("State changed:", snapshot(state));
});

Architecture

Valtio is built around several key components:

  • Proxy Core: Self-tracking proxy objects that detect mutations without explicit state setters
  • Snapshot System: Immutable snapshots for safe reading in React components and other contexts
  • Subscription Engine: Fine-grained change detection and notification system
  • React Integration: Optimized hooks that only re-render when accessed properties change
  • Utility Library: Additional tools for advanced use cases like reactive effects, DevTools integration, and collection handling

Capabilities

Core Proxy System

Foundation of Valtio's reactivity providing proxy creation, immutable snapshots, and change subscriptions. Essential for all state management scenarios.

function proxy<T extends object>(baseObject?: T): T;
function snapshot<T extends object>(proxyObject: T): Snapshot<T>;
function subscribe<T extends object>(
  proxyObject: T,
  callback: (unstable_ops: Op[]) => void,
  notifyInSync?: boolean
): () => void;

Core Proxy System

React Integration

React hooks optimized for Valtio's proxy system, providing automatic re-rendering and ergonomic state access patterns.

function useSnapshot<T extends object>(
  proxyObject: T,
  options?: { sync?: boolean }
): Snapshot<T>;

function useProxy<T extends object>(proxy: T): T;

React Integration

Advanced Utilities

Extended functionality including reactive effects, key-specific subscriptions, DevTools integration, deep cloning, and specialized collections.

function watch(
  callback: (get: <T extends object>(proxyObject: T) => T) => void | (() => void) | Promise<void | (() => void)>,
  options?: { sync?: boolean }
): () => void;

function subscribeKey<T extends object, K extends keyof T>(
  proxyObject: T,
  key: K,
  callback: (value: T[K]) => void,
  notifyInSync?: boolean
): () => void;

function devtools<T extends object>(
  proxyObject: T,
  options?: { enabled?: boolean; name?: string }
): (() => void) | undefined;

Advanced Utilities

Types

type Snapshot<T> = T extends { $$valtioSnapshot: infer S }
  ? S
  : T extends SnapshotIgnore
    ? T
    : T extends object
      ? { readonly [K in keyof T]: Snapshot<T[K]> }
      : T;

type Op =
  | [op: 'set', path: (string | symbol)[], value: unknown, prevValue: unknown]
  | [op: 'delete', path: (string | symbol)[], prevValue: unknown];