• Stars
    star
    8,738
  • Rank 4,167 (Top 0.09 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created about 4 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

💊 Valtio makes proxy-state simple for React and Vanilla

valtio



npm i valtio makes proxy-state simple

Build Status Build Size Version Downloads Discord Shield

Wrap your state object

Valtio turns the object you pass it into a self-aware proxy.

import { proxy, useSnapshot } from 'valtio'

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

Mutate from anywhere

You can make changes to it in the same way you would to a normal js-object.

setInterval(() => {
  ++state.count
}, 1000)

React via useSnapshot

Create a local snapshot that catches changes. Rule of thumb: read from snapshots in render function, otherwise use the source. The component will only re-render when the parts of the state you access have changed, it is render-optimized.

// This will re-render on `state.count` change but not on `state.text` change
function Counter() {
  const snap = useSnapshot(state)
  return (
    <div>
      {snap.count}
      <button onClick={() => ++state.count}>+1</button>
    </div>
  )
}
Note for TypeScript users: Return type of useSnapshot can be too strict.

The snap variable returned by useSnapshot is a (deeply) read-only object. Its type has readonly attribute, which may be too strict for some use cases.

To mitigate typing difficulties, you might want to loosen the type definition:

declare module 'valtio' {
  function useSnapshot<T extends object>(p: T): T
}

See #327 for more information.

Note: useSnapshot returns a new proxy for render optimization.

Internally, useSnapshot calls snapshot in valtio/vanilla, and wraps the snapshot object with another proxy to detect property access. This feature is based on proxy-compare.

Two kinds of proxies are used for different purposes:

  • proxy() from valtio/vanilla is for mutation tracking or write tracking.
  • createProxy() from proxy-compare is for usage tracking or read tracking.
Use of this is for expert users.

Valtio tries best to handle this behavior but it's hard to understand without familiarity.

const state = proxy({
  count: 0,
  inc() {
    ++this.count
  },
})
state.inc() // `this` points to `state` and it works fine
const snap = useSnapshot(state)
snap.inc() // `this` points to `snap` and it doesn't work because snapshot is frozen

To avoid this pitfall, the recommended pattern is not to use this and prefer arrow function.

const state = proxy({
  count: 0,
  inc: () => {
    ++state.count
  },
})

If you are new to this, it's highly recommended to use eslint-plugin-valtio.

Subscribe from anywhere

You can access state outside of your components and subscribe to changes.

import { subscribe } from 'valtio'

// Subscribe to all state changes
const unsubscribe = subscribe(state, () =>
  console.log('state has changed to', state)
)
// Unsubscribe by calling the result
unsubscribe()

You can also subscribe to a portion of state.

const state = proxy({ obj: { foo: 'bar' }, arr: ['hello'] })

subscribe(state.obj, () => console.log('state.obj has changed to', state.obj))
state.obj.foo = 'baz'

subscribe(state.arr, () => console.log('state.arr has changed to', state.arr))
state.arr.push('world')

To subscribe to a primitive value of state, consider subscribeKey in utils.

import { subscribeKey } from 'valtio/utils'

const state = proxy({ count: 0, text: 'hello' })
subscribeKey(state, 'count', (v) =>
  console.log('state.count has changed to', v)
)

There is another util watch which might be convenient in some cases.

import { watch } from 'valtio/utils'

const state = proxy({ count: 0 })
const stop = watch((get) => {
  console.log('state has changed to', get(state)) // auto-subscribe on use
})

Suspend your components

Valtio supports React-suspense and will throw promises that you access within a components render function. This eliminates all the async back-and-forth, you can access your data directly while the parent is responsible for fallback state and error handling.

const state = proxy({ post: fetch(url).then((res) => res.json()) })

function Post() {
  const snap = useSnapshot(state)
  return <div>{snap.post.title}</div>
}

function App() {
  return (
    <Suspense fallback={<span>waiting...</span>}>
      <Post />
    </Suspense>
  )
}

Holding objects in state without tracking them

This may be useful if you have large, nested objects with accessors that you don't want to proxy. ref allows you to keep these objects inside the state model.

See #61 and #178 for more information.

import { proxy, ref } from 'valtio'

const state = proxy({
  count: 0,
  dom: ref(document.body),
})

Update transiently (for often occurring state-changes)

You can read state in a component without causing re-render.

function Foo() {
  const { count, text } = state
  // ...

Or, you can have more control with subscribing in useEffect.

function Foo() {
  const total = useRef(0)
  useEffect(() => subscribe(state.arr, () => {
    total.current = state.arr.reduce((p, c) => p + c)
  }), [])
  // ...

Update synchronously

By default, state mutations are batched before triggering re-render. Sometimes, we want to disable the batching. The known use case of this is <input> #270.

function TextBox() {
  const snap = useSnapshot(state, { sync: true })
  return (
    <input value={snap.text} onChange={(e) => (state.text = e.target.value)} />
  )
}

Dev tools

You can use Redux DevTools Extension for plain objects and arrays.

import { devtools } from 'valtio/utils'

const state = proxy({ count: 0, text: 'hello' })
const unsub = devtools(state, { name: 'state name', enabled: true })
Manipulating state with Redux DevTools The screenshot below shows how to use Redux DevTools to manipulate state. First select the object from the instances drop down. Then type in a JSON object to dispatch. Then click "Dispatch". Notice how it changes the state.
image

Use it vanilla

Valtio is not tied to React, you can use it in vanilla-js.

import { proxy, subscribe, snapshot } from 'valtio/vanilla'
// import { ... } from 'valtio/vanilla/utils'

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

subscribe(state, () => {
  console.log('state is mutated')
  const obj = snapshot(state) // A snapshot is an immutable object
})

useProxy util

While the separation of proxy state and its snapshot is important, it's confusing for beginners. We have a convenient util to improve developer experience. useProxy returns shallow proxy state and its snapshot, meaning you can only mutate on root level.

import { useProxy } from 'valtio/utils'

const state = proxy({ count: 1 })

const Component = () => {
  // useProxy returns a special proxy that can be used both in render and callbacks
  // The special proxy has to be used directly in a function scope. You can't destructure it outside the scope.
  const $state = useProxy(state)
  return (
    <div>
      {$state.count}
      <button onClick={() => ++$state.count}>+1</button>
    </div>
  )
}

derive util

You can subscribe to some proxies and create a derived proxy.

import { derive } from 'valtio/utils'

// create a base proxy
const state = proxy({
  count: 1,
})

// create a derived proxy
const derived = derive({
  doubled: (get) => get(state).count * 2,
})

// alternatively, attach derived properties to an existing proxy
derive(
  {
    tripled: (get) => get(state).count * 3,
  },
  {
    proxy: state,
  }
)

proxyWithHistory util

This is a utility function to create a proxy with snapshot history.

import { proxyWithHistory } from 'valtio/utils'

const state = proxyWithHistory({ count: 0 })
console.log(state.value) // ---> { count: 0 }
state.value.count += 1
console.log(state.value) // ---> { count: 1 }
state.undo()
console.log(state.value) // ---> { count: 0 }
state.redo()
console.log(state.value) // ---> { count: 1 }

proxySet util

This is to create a proxy which mimic the native Set behavior. The API is the same as Set API

import { proxySet } from 'valtio/utils'

const state = proxySet([1, 2, 3])
//can be used inside a proxy as well
//const state = proxy({
//    count: 1,
//    set: proxySet()
//})

state.add(4)
state.delete(1)
state.forEach((v) => console.log(v)) // 2,3,4

proxyMap util

This is to create a proxy which emulate the native Map behavior. The API is the same as Map API

import { proxyMap } from 'valtio/utils'

const state = proxyMap([
  ['key', 'value'],
  ['key2', 'value2'],
])
state.set('key', 'value')
state.delete('key')
state.get('key') // ---> value
state.forEach((value, key) => console.log(key, value)) // ---> "key", "value", "key2", "value2"

Compatibility

Valtio works with React with hooks support (>=16.8). It only depends on react and works with any renderers such as react-dom, react-native, react-three-fiber, and so on.

Valtio works on Node.js, Next.js and other frameworks.

Valtio also works without React. See vanilla.

Plugins

Recipes

Valtio is unopinionated about best practices. The community is working on recipes on wiki pages.

More Repositories

1

zustand

ðŸŧ Bear necessities for state management in React
TypeScript
45,348
star
2

react-spring

✌ïļ A spring physics based React animation library
TypeScript
27,857
star
3

react-three-fiber

ðŸ‡Ļ🇭 A React renderer for Three.js
TypeScript
26,202
star
4

jotai

ðŸ‘ŧ Primitive and flexible state management for React
TypeScript
18,007
star
5

use-gesture

👇Bread n butter utility for component-tied mouse/touch gestures in React and Vanilla Javascript.
TypeScript
8,861
star
6

drei

ðŸĨ‰ useful helpers for react-three-fiber
JavaScript
8,042
star
7

leva

🌋 React-first components GUI
TypeScript
4,825
star
8

gltfjsx

ðŸŽŪ Turns GLTFs into JSX components
JavaScript
4,251
star
9

use-cannon

👋ðŸ’Ģ physics based hooks for @react-three/fiber
TypeScript
2,700
star
10

react-three-next

React Three Fiber, Threejs, Nextjs starter
JavaScript
2,370
star
11

postprocessing

A post processing library for three.js.
JavaScript
2,263
star
12

racing-game

🏎 Open source racing game developed by everyone willing
TypeScript
2,120
star
13

xr

ðŸĪģ VR/AR for react-three-fiber
TypeScript
2,051
star
14

uikit

ðŸŽĻ user interfaces for react-three-fiber
TypeScript
2,048
star
15

react-three-flex

💊ðŸ“Ķ Flexbox for react-three-fiber
TypeScript
1,640
star
16

suspend-react

ðŸšĨ Async/await for React components
TypeScript
1,358
star
17

react-postprocessing

📎 postprocessing for react-three-fiber
JavaScript
1,074
star
18

detect-gpu

Classifies GPUs based on their 3D rendering benchmark score allowing the developer to provide sensible default settings for graphically intensive applications.
TypeScript
1,017
star
19

react-three-rapier

ðŸĪš Rapier physics in React
TypeScript
1,005
star
20

lamina

🍰 An extensible, layer based shader material for ThreeJS
TypeScript
1,005
star
21

its-fine

ðŸķðŸ”Ĩ A collection of escape hatches for React.
TypeScript
978
star
22

react-use-measure

🙌 Utility to measure view bounds
TypeScript
832
star
23

react-nil

⃝ A react null renderer
TypeScript
785
star
24

maath

ðŸŠķ Math helpers for the rest of us
TypeScript
783
star
25

threejs-journey

⚛ïļ Bruno Simons journey demos in React
TypeScript
718
star
26

three-stdlib

📚 Stand-alone library of threejs examples designed to run without transpilation in node & browser
JavaScript
651
star
27

react-three-editor

🔌 A one of a kind scene editor that writes changes back into your code
TypeScript
615
star
28

react-three-a11y

â™ŋïļ Accessibility tools for React Three Fiber
TypeScript
534
star
29

ecctrl

ðŸ•đïļ A floating rigibody character controller
TypeScript
498
star
30

react-three-offscreen

📚 Offscreen worker canvas for react-three-fiber
TypeScript
443
star
31

react-zdog

⚡ïļðŸķ React bindings for zdog
JavaScript
441
star
32

drei-vanilla

ðŸĶ drei-inspired helpers for threejs
TypeScript
436
star
33

use-asset

ðŸ“Ķ A promise caching strategy for React Suspense
TypeScript
413
star
34

tunnel-rat

🐀 Non gratum anus rodentum
TypeScript
329
star
35

react-three-csg

🚧 Constructive solid geometry for React
TypeScript
264
star
36

react-three-lgl

🔆 A React abstraction for the LGL Raycaster
TypeScript
262
star
37

gltf-react-three

Convert GLTF files to React Three Fiber Components
JavaScript
258
star
38

market

ðŸ“Ķ Download CC0 assets ready to use in your next 3D Project
JavaScript
250
star
39

component-material

ðŸ§Đ Compose modular materials in React
TypeScript
160
star
40

env

💄 An app to create, edit, and preview HDR environment maps in the browser
TypeScript
151
star
41

react-ogl

ðŸĶī A barebones react renderer for ogl.
TypeScript
150
star
42

use-p2

👋ðŸ’Ģ 2d physics hooks for @react-three/fiber
TypeScript
144
star
43

react-spring-examples

JavaScript
139
star
44

react-three-gpu-pathtracer

⚡ïļ A React abstraction for the popular three-gpu-pathtracer
TypeScript
132
star
45

react-three-lightmap

In-browser lightmap/AO baker for react-three-fiber and ThreeJS
TypeScript
127
star
46

cannon-es-debugger

Wireframe debugger for use with cannon-es https://github.com/react-spring/cannon-es
HTML
102
star
47

rafz

💍 One loop to frame them all.
TypeScript
96
star
48

docs

ðŸ–Ļïļ mdx documentation generator for `pmndrs/*/docs` folders
TypeScript
91
star
49

assets

ðŸ“Ķ Importable base64 encoded CC0 assets
Makefile
91
star
50

swc-jotai

Rust
88
star
51

react-three-jolt

⚡ Jolt physics in React
TypeScript
84
star
52

react-three-scissor

✂ Multiple scenes, one canvas! WebGL Scissoring implementation for React Three Fiber.
TypeScript
79
star
53

eslint-plugin-valtio

An eslint plugin for better valtio experience
JavaScript
74
star
54

react-three-babel

🛍 A Babel plugin that automatically builds the extend catalogue of known native Three.js elements
TypeScript
60
star
55

react-spring.io

✌ïļ A spring physics based React animation library
TypeScript
56
star
56

r3f-website

Website for React Three Fiber
JavaScript
27
star
57

directed

A flexible, minimal scheduler written in TypeScript
TypeScript
24
star
58

market-assets

JavaScript
19
star
59

react-three-8thwall

JavaScript
17
star
60

drei-assets

JavaScript
16
star
61

discord

ðŸĪ– Poimandres Discord Bot
TypeScript
10
star
62

branding

TypeScript
7
star
63

market-assets-do

JavaScript
5
star
64

envinfo

Easily collect useful information for bug reports
JavaScript
4
star
65

leva-wg

1
star