[
{
"path": ".codesandbox/ci.json",
"content": "{\n \"packages\": [\"dist\"],\n \"sandboxes\": [\n \"new\",\n \"react-typescript-react-ts\",\n \"simple-react-browserify-x9yni\",\n \"simple-snowpack-react-o1gmx\",\n \"react-parcel-onewf\"\n ],\n \"node\": \"18\"\n}\n"
},
{
"path": ".github/DISCUSSION_TEMPLATE/bug-report.yml",
"content": "labels: ['bug']\nbody:\n - type: markdown\n attributes:\n value: If you don't have a reproduction link, please choose a different category.\n - type: textarea\n attributes:\n label: Bug Description\n description: Describe the bug you encountered\n validations:\n required: true\n - type: input\n attributes:\n label: Reproduction Link\n description: A link to a [TypeScript Playground](https://www.typescriptlang.org/play), a [StackBlitz Project](https://stackblitz.com/) or something else with a minimal reproduction.\n validations:\n required: true\n"
},
{
"path": ".github/FUNDING.yml",
"content": "# These are supported funding model platforms\n\ngithub: [dai-shi] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]\npatreon: # Replace with a single Patreon username\nopen_collective: # Replace with a single Open Collective username\nko_fi: # Replace with a single Ko-fi username\ntidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel\ncommunity_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry\nliberapay: # Replace with a single Liberapay username\nissuehunt: # Replace with a single IssueHunt username\notechie: # Replace with a single Otechie username\nlfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry\ncustom: ['https://daishi.gumroad.com/l/learn-valtio'] # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']\n"
},
{
"path": ".github/ISSUE_TEMPLATE/bug_report.md",
"content": "---\nname: Assigned issue\nabout: This is to create a new issue that already has an assignee. Please open a new discussion otherwise.\ntitle: ''\nlabels: ''\nassignees: ''\n---\n"
},
{
"path": ".github/ISSUE_TEMPLATE/config.yml",
"content": "blank_issues_enabled: false\ncontact_links:\n - name: Bug Reports\n url: https://github.com/pmndrs/valtio/discussions/new?category=bug-report\n about: Please post bug reports here.\n - name: Questions\n url: https://github.com/pmndrs/valtio/discussions/new?category=q-a\n about: Please post questions here.\n - name: Other Discussions\n url: https://github.com/pmndrs/valtio/discussions/new/choose\n about: Please post ideas and general discussions here.\n"
},
{
"path": ".github/pull_request_template.md",
"content": "## Related Bug Reports or Discussions\n\nFixes #\n\n## Summary\n\n## Check List\n\n- [ ] `pnpm run fix` for formatting and linting code and docs\n"
},
{
"path": ".github/workflows/compressed-size.yml",
"content": "name: Compressed Size\n\non: [pull_request]\n\njobs:\n compressed_size:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0\n - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0\n with:\n node-version: 'lts/*'\n cache: 'pnpm'\n - uses: preactjs/compressed-size-action@49c7ff02f46adc39a83c24e91f6110ba8138a19d # v3\n with:\n pattern: './dist/**/*.{js,mjs}'\n"
},
{
"path": ".github/workflows/preview-release.yml",
"content": "name: Preview Release\n\non: [push, pull_request]\n\njobs:\n preview_release:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0\n - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0\n with:\n node-version: 'lts/*'\n cache: 'pnpm'\n - run: pnpm install\n - run: pnpm run build\n - run: pnpm dlx pkg-pr-new publish './dist' --compact --template './examples/*'\n"
},
{
"path": ".github/workflows/publish.yml",
"content": "name: Publish\n\non:\n release:\n types: [published]\n\npermissions:\n id-token: write\n contents: read\n\njobs:\n publish:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0\n - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0\n with:\n node-version: 'lts/*'\n registry-url: 'https://registry.npmjs.org'\n cache: 'pnpm'\n - run: pnpm install\n - run: pnpm run build\n - run: npm publish\n working-directory: dist\n"
},
{
"path": ".github/workflows/test-multiple-builds.yml",
"content": "name: Test Multiple Builds\n\non:\n push:\n branches: [main]\n pull_request:\n types: [opened, synchronize]\n\njobs:\n test_multiple_builds:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n build: [cjs, esm]\n env: [development] # [development, production]\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0\n - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0\n with:\n node-version: 'lts/*'\n cache: 'pnpm'\n - run: pnpm install\n - run: pnpm run build\n - name: Patch for DEV-ONLY\n if: ${{ matrix.env == 'development' }}\n run: |\n sed -i~ \"s/it[.a-zA-Z]*('\\[DEV-ONLY\\]/it('/\" tests/*.ts tests/*.tsx\n sed -i~ \"s/it[.a-zA-Z]*('\\[PRD-ONLY\\]/it.skip('/\" tests/*.ts tests/*.tsx\n - name: Patch for PRD-ONLY\n if: ${{ matrix.env == 'production' }}\n run: |\n sed -i~ \"s/it[.a-zA-Z]*('\\[PRD-ONLY\\]/it('/\" tests/*.ts tests/*.tsx\n sed -i~ \"s/it[.a-zA-Z]*('\\[DEV-ONLY\\]/it.skip('/\" tests/*.ts tests/*.tsx\n - name: Patch for CJS\n if: ${{ matrix.build == 'cjs' }}\n run: |\n sed -i~ \"s/resolve('\\.\\/src\\(.*\\)\\.ts')/resolve('\\.\\/dist\\1.js')/\" vitest.config.mts\n - name: Patch for ESM\n if: ${{ matrix.build == 'esm' }}\n run: |\n sed -i~ \"s/resolve('\\.\\/src\\(.*\\)\\.ts')/resolve('\\.\\/dist\\/esm\\1.mjs')/\" vitest.config.mts\n sed -i~ \"1s/^/import.meta.env.MODE='${NODE_ENV}';/\" tests/*.ts tests/*.tsx\n env:\n NODE_ENV: ${{ matrix.env }}\n - name: Test ${{ matrix.build }} ${{ matrix.env }}\n run: |\n pnpm run test:spec\n env:\n NODE_ENV: ${{ matrix.env }}\n"
},
{
"path": ".github/workflows/test-multiple-versions.yml",
"content": "name: Test Multiple Versions\n\non:\n push:\n branches: [main]\n pull_request:\n types: [opened, synchronize]\n\njobs:\n test_multiple_versions:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n react:\n - 18.0.0\n - 18.1.0\n - 18.2.0\n - 18.3.1\n - 19.0.0\n - 19.1.0\n - 19.2.0\n - 19.3.0-canary-e0cc7202-20260227\n - 0.0.0-experimental-e0cc7202-20260227\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0\n - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0\n with:\n node-version: 'lts/*'\n cache: 'pnpm'\n - run: pnpm install\n - name: Install legacy testing-library\n if: ${{ startsWith(matrix.react, '16.') || startsWith(matrix.react, '17.') }}\n run: pnpm add -D @testing-library/react@12.1.4\n - name: Patch for React 16\n if: ${{ startsWith(matrix.react, '16.') }}\n run: |\n sed -i~ '1s/^/import React from \"react\";/' tests/*.tsx\n sed -i~ 's/\"jsx\": \"react-jsx\"/\"jsx\": \"react\"/' tsconfig.json\n sed -i~ 's/import\\.meta\\.env[?]\\.MODE/\"DEVELOPMENT\".toLowerCase()/' src/*.ts src/*/*.ts src/*/*/*.ts\n - name: Test ${{ matrix.react }}\n run: |\n pnpm add -D react@${{ matrix.react }} react-dom@${{ matrix.react }}\n pnpm run test:spec\n"
},
{
"path": ".github/workflows/test-old-typescript.yml",
"content": "name: Test Old TypeScript\n\non:\n push:\n branches: [main]\n pull_request:\n types: [opened, synchronize]\n\njobs:\n test_old_typescript:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n typescript:\n - 5.9.3\n - 5.8.3\n - 5.7.3\n - 5.6.3\n - 5.5.4\n - 5.4.5\n - 5.3.3\n - 5.2.2\n - 5.1.6\n - 5.0.4\n - 4.9.5\n - 4.8.4\n - 4.7.4\n - 4.6.4\n - 4.5.5\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0\n - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0\n with:\n node-version: 'lts/*'\n cache: 'pnpm'\n - run: pnpm install\n - run: pnpm run build\n - name: Patch for all TS\n run: |\n sed -i~ 's/\"isolatedDeclarations\": true,//' tsconfig.json\n - name: Patch for v4/v3 TS\n if: ${{ startsWith(matrix.typescript, '4.') || startsWith(matrix.typescript, '3.') }}\n run: |\n sed -i~ 's/\"verbatimModuleSyntax\": true,//' tsconfig.json\n - name: Patch for Old TS\n if: ${{ matrix.typescript == '5.5.4' || matrix.typescript == '5.4.5' || matrix.typescript == '5.3.3' || matrix.typescript == '5.2.2' || matrix.typescript == '5.1.6' || matrix.typescript == '5.0.4' || matrix.typescript == '4.9.5' || matrix.typescript == '4.8.4' || matrix.typescript == '4.7.4' || matrix.typescript == '4.6.4' || matrix.typescript == '4.5.5' }}\n run: |\n sed -i~ 's/\"moduleResolution\": \"bundler\",/\"moduleResolution\": \"node\",/' tsconfig.json\n sed -i~ 's/\"allowImportingTsExtensions\": true,//' tsconfig.json\n sed -i~ 's/\"valtio\": \\[\"\\.\\/src\\/index\\.ts\"\\],/\"valtio\": [\".\\/dist\\/index.d.ts\"],/' tsconfig.json\n sed -i~ 's/\"valtio\\/\\*\": \\[\"\\.\\/src\\/\\*\\.ts\"\\]/\"valtio\\/*\": [\".\\/dist\\/*.d.ts\"]/' tsconfig.json\n sed -i~ 's/\"include\": .*/\"include\": [\"src\\/types.d.ts\", \"dist\\/**\\/*\", \"tests\\/**\\/*\"],/' tsconfig.json\n - name: Patch for Older TS\n if: ${{ matrix.typescript == '4.7.4' || matrix.typescript == '4.6.4' || matrix.typescript == '4.5.5' }}\n run: |\n pnpm json -I -f package.json -e \"this.resolutions={}; this.resolutions['@types/node']='18.13.0';\"\n pnpm add -D @types/node@18.13.0\n pnpm add -D vitest@3.2.4 @vitest/coverage-v8@3.2.4 @vitest/ui@3.2.4\n - name: Install old TypeScript\n run: pnpm add -D typescript@${{ matrix.typescript }}\n - name: Test ${{ matrix.typescript }}\n run: pnpm run test:types\n"
},
{
"path": ".github/workflows/test.yml",
"content": "name: Test\n\non:\n push:\n branches: [main]\n pull_request:\n types: [opened, synchronize]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0\n - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0\n with:\n node-version: 'lts/*'\n cache: 'pnpm'\n - run: pnpm install\n - run: pnpm run test:format\n - run: pnpm run test:types\n - run: pnpm run test:lint\n - run: pnpm run test:spec\n - run: pnpm run build # we don't have any other workflows to test build\n"
},
{
"path": ".gitignore",
"content": "# dependencies\nnode_modules\n.pnp\n.pnp.js\n\n# testing\ncoverage\n\n# production\ndist\nbuild\n\n# dotenv environment variables file\n.env\n.env.local\n.env.development.local\n.env.test.local\n.env.production.local\n\n# logs\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# misc\n.DS_Store\n.idea\n\n# examples\nexamples/**/*/package-lock.json\nexamples/**/*/yarn.lock\nexamples/**/*/pnpm-lock.yaml\nexamples/**/*/bun.lockb\n"
},
{
"path": ".prettierignore",
"content": "dist\npnpm-lock.yaml\n"
},
{
"path": "CONTRIBUTING.md",
"content": "# Contributing\n\n## General Guideline\n\n### Reporting Issues\n\nIf you have found what you think is a bug, please [start a discussion](https://github.com/pmndrs/valtio/discussions/new?category=bug-report).\n\nFor any usage questions, please [start a discussion](https://github.com/pmndrs/valtio/discussions/new?category=q-a).\n\n### Suggesting New Features\n\nIf you are here to suggest a feature, first [start a discussion](https://github.com/pmndrs/valtio/discussions/new?category=ideas) if it does not already exist. From there, we will discuss use-cases for the feature and then finally discuss how it could be implemented.\n\n### Committing\n\nWe are applying [conventional commit spec](https://www.conventionalcommits.org/en/v1.0.0/) here. In short, that means a commit has to be one of the following types:\n\nYour commit type must be one of the following:\n\n- **feat**: A new feature.\n- **fix**: A bug fix.\n- **refactor**: A code change that neither fixes a bug nor adds a feature.\n- **chore**: Changes to the build process, configuration, dependencies, CI/CD pipelines, or other auxiliary tools and libraries.\n- **docs**: Documentation-only changes.\n- **test**: Adding missing or correcting existing tests.\n\nIf you are unfamiliar with the usage of conventional commits,\nthe short version is to simply specify the type as a first word,\nand follow it with a colon and a space, then start your message\nfrom a lowercase letter, like this:\n\n```\nfeat: add a 'foo' type support\n```\n\nYou can also specify the scope of the commit in the parentheses after a type:\n\n```\nfix(react): change the 'bar' parameter type\n```\n\n### Development\n\nIf you would like to contribute by fixing an open issue or developing a new feature you can use this suggested workflow:\n\n#### General\n\n1. Fork this repository.\n2. Create a new feature branch based off the `main` branch.\n3. Follow the [Core](#Core) and/or the [Documentation](#Documentation) guide below and come back to this once done.\n4. Run `pnpm run fix:format` to format the code.\n5. Git stage your required changes and commit (review the commit guidelines below).\n6. Submit the PR for review.\n\n##### Core\n\n1. Run `pnpm install` to install dependencies.\n2. Create failing tests for your fix or new feature in the [`tests`](./tests/) folder.\n3. Implement your changes.\n4. Run `pnpm run build` to build the library. _(Pro-tip: `pnpm run build-watch` runs the build in watch mode)_\n5. Run the tests by running `pnpm run test` and ensure that they pass.\n6. You can use `pnpm link` to sym-link this package and test it locally on your own project. Alternatively, you may use CodeSandbox CI's canary releases to test the changes in your own project. (requires a PR to be created first)\n7. Follow step 4 and onwards from the [General](#General) guide above to bring it to the finish line.\n\n### Pull Requests\n\nPlease try to keep your pull request focused in scope and avoid including unrelated commits.\n\nAfter you have submitted your pull request, we'll try to get back to you as soon as possible. We may suggest some changes or request improvements, therefore, please check ā [\"Allow edits from maintainers\"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) on your PR.\n\n## Valtio-specific Guideline\n\n##### Documentation\n\n1. Navigate to the [`website`](./website/) folder. (e.g., `cd website`).\n2. Run `pnpm install` to install dependencies in the `website` folder.\n3. Run `pnpm run dev` to start the dev server.\n4. Navigate to [`http://localhost:3000`](http://localhost:3000) to view the documents.\n5. Navigate to the [`docs`](./docs/) folder and make necessary changes to the documents.\n6. Add your changes to the documents and see them live reloaded in the browser.\n7. Follow step 4 and onwards from the [General](#General) guide above to bring it to the finish line.\n\nThank you for contributing! :heart:\n"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) 2020 Poimandres\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "\n \n \n\nnpm install valtio makes proxy-state simple\n\n[](https://github.com/pmndrs/valtio/actions/workflows/test.yml?query=branch%3Amain)\n[](https://bundlephobia.com/result?p=valtio)\n[](https://www.npmjs.com/package/valtio)\n[](https://www.npmjs.com/package/valtio)\n[](https://discord.gg/poimandres)\n\n#### Wrap your state object\n\nValtio turns the object you pass it into a self-aware proxy.\n\n```jsx\nimport { proxy, useSnapshot } from 'valtio'\n\nconst state = proxy({ count: 0, text: 'hello' })\n```\n\n#### Mutate from anywhere\n\nYou can make changes to it in the same way you would to a normal js-object.\n\n```jsx\nsetInterval(() => {\n ++state.count\n}, 1000)\n```\n\n#### React via useSnapshot\n\nCreate 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.\n\n```jsx\n// This will re-render on `state.count` change but not on `state.text` change\nfunction Counter() {\n const snap = useSnapshot(state)\n return (\n
\n {snap.count}\n \n
\n )\n}\n```\n\n\nNote for TypeScript users: Return type of useSnapshot can be too strict.\n\nThe `snap` variable returned by `useSnapshot` is a (deeply) read-only object.\nIts type has `readonly` attribute, which may be too strict for some use cases.\n\nTo mitigate typing difficulties, you might want to loosen the type definition:\n\n```ts\ndeclare module 'valtio' {\n function useSnapshot(p: T): T\n}\n```\n\nSee [#327](https://github.com/pmndrs/valtio/issues/327) for more information.\n\n\n\n\nNote: useSnapshot returns a new proxy for render optimization.\n\nInternally, `useSnapshot` calls `snapshot` in valtio/vanilla,\nand wraps the snapshot object with another proxy to detect property access.\nThis feature is based on [proxy-compare](https://github.com/dai-shi/proxy-compare).\n\nTwo kinds of proxies are used for different purposes:\n\n- `proxy()` from `valtio/vanilla` is for mutation tracking or write tracking.\n- `createProxy()` from `proxy-compare` is for usage tracking or read tracking.\n\n\n\nUse of this is for expert users.\n\nValtio tries best to handle `this` behavior\nbut it's hard to understand without familiarity.\n\n```js\nconst state = proxy({\n count: 0,\n inc() {\n ++this.count\n },\n})\nstate.inc() // `this` points to `state` and it works fine\nconst snap = useSnapshot(state)\nsnap.inc() // `this` points to `snap` and it doesn't work because snapshot is frozen\n```\n\nTo avoid this pitfall, the recommended pattern is not to use `this` and prefer arrow function.\n\n```js\nconst state = proxy({\n count: 0,\n inc: () => {\n ++state.count\n },\n})\n```\n\n\n\nIf you are new to this, it's highly recommended to use\n[eslint-plugin-valtio](https://github.com/pmndrs/eslint-plugin-valtio).\n\n#### Subscribe from anywhere\n\nYou can access state outside of your components and subscribe to changes.\n\n```jsx\nimport { subscribe } from 'valtio'\n\n// Subscribe to all state changes\nconst unsubscribe = subscribe(state, () =>\n console.log('state has changed to', state),\n)\n// Unsubscribe by calling the result\nunsubscribe()\n```\n\nYou can also subscribe to a portion of state.\n\n```jsx\nconst state = proxy({ obj: { foo: 'bar' }, arr: ['hello'] })\n\nsubscribe(state.obj, () => console.log('state.obj has changed to', state.obj))\nstate.obj.foo = 'baz'\n\nsubscribe(state.arr, () => console.log('state.arr has changed to', state.arr))\nstate.arr.push('world')\n```\n\nTo subscribe to a primitive value of state, consider `subscribeKey` in utils.\n\n```jsx\nimport { subscribeKey } from 'valtio/utils'\n\nconst state = proxy({ count: 0, text: 'hello' })\nsubscribeKey(state, 'count', (v) =>\n console.log('state.count has changed to', v),\n)\n```\n\nThere is another util `watch` which might be convenient in some cases.\n\n```jsx\nimport { watch } from 'valtio/utils'\n\nconst state = proxy({ count: 0 })\nconst stop = watch((get) => {\n console.log('state has changed to', get(state)) // auto-subscribe on use\n})\n```\n\n#### Suspend your components\n\nValtio is compatible with React 19 `use` hook. 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.\n\n```jsx\nimport { use } from 'react' // React 19\n// import { use } from 'react18-use' // React 18\n\nconst state = proxy({ post: fetch(url).then((res) => res.json()) })\n\nfunction Post() {\n const snap = useSnapshot(state)\n return
{use(snap.post).title}
\n}\n\nfunction App() {\n return (\n waiting...}>\n \n \n )\n}\n```\n\nIt still suffers from \"de-opt\", which prevents `useTransition` to work well. To mitigate it, there is a third-party library [use-valtio](https://github.com/valtiojs/use-valtio).\n\n#### Holding objects in state without tracking them\n\nThis 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.\n\nSee [#61](https://github.com/pmndrs/valtio/issues/61) and [#178](https://github.com/pmndrs/valtio/issues/178) for more information.\n\n```js\nimport { proxy, ref } from 'valtio'\n\nconst state = proxy({\n count: 0,\n dom: ref(document.body),\n})\n```\n\n#### Update transiently (for often occurring state-changes)\n\nYou can read state in a component without causing re-render.\n\n```jsx\nfunction Foo() {\n const { count, text } = state\n // ...\n```\n\nOr, you can have more control with subscribing in useEffect.\n\n```jsx\nfunction Foo() {\n const total = useRef(0)\n useEffect(() => subscribe(state.arr, () => {\n total.current = state.arr.reduce((p, c) => p + c)\n }), [])\n // ...\n```\n\n#### Update synchronously\n\nBy default, state mutations are batched before triggering re-render.\nSometimes, we want to disable the batching.\nThe known use case of this is `` [#270](https://github.com/pmndrs/valtio/issues/270).\n\n```jsx\nfunction TextBox() {\n const snap = useSnapshot(state, { sync: true })\n return (\n (state.text = e.target.value)} />\n )\n}\n```\n\n#### Dev tools\n\nYou can use [Redux DevTools Extension](https://github.com/reduxjs/redux-devtools) for plain objects and arrays.\n\n```jsx\nimport { devtools } from 'valtio/utils'\n\nconst state = proxy({ count: 0, text: 'hello' })\nconst unsub = devtools(state, { name: 'state name', enabled: true })\n```\n\n\n Manipulating state with Redux DevTools\nThe 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.\n\n \n\n\n\n#### Use it vanilla\n\nValtio is not tied to React, you can use it in vanilla-js.\n\n```jsx\nimport { proxy, subscribe, snapshot } from 'valtio/vanilla'\n// import { ... } from 'valtio/vanilla/utils'\n\nconst state = proxy({ count: 0, text: 'hello' })\n\nsubscribe(state, () => {\n console.log('state is mutated')\n const obj = snapshot(state) // A snapshot is an immutable object\n})\n```\n\n#### `useProxy` util\n\nWhile the separation of proxy state and its snapshot is important,\nit's confusing for beginners.\nWe have a convenient util to improve developer experience. useProxy returns shallow proxy state and its snapshot, meaning you can only mutate on root level.\n\n```js\nimport { useProxy } from 'valtio/utils'\n\nconst state = proxy({ count: 1 })\n\nconst Component = () => {\n // useProxy returns a special proxy that can be used both in render and callbacks\n // The special proxy has to be used directly in a function scope. You can't destructure it outside the scope.\n const $state = useProxy(state)\n return (\n
\n {$state.count}\n \n
\n )\n}\n```\n\n#### Computed properties\n\nYou can define computed properties with object getters.\n\n```js\nconst state = proxy({\n count: 1,\n get doubled() {\n return this.count * 2\n },\n})\n```\n\nConsider it as an advanced usage, because the behavior of `this` is sometimes confusing.\n\nFor more information, check out [this guide](./docs/guides/computed-properties.mdx).\n\n#### `proxySet` util\n\nThis is to create a proxy which mimic the native Set behavior. The API is the same as Set API\n\n```js\nimport { proxySet } from 'valtio/utils'\n\nconst state = proxySet([1, 2, 3])\n//can be used inside a proxy as well\n//const state = proxy({\n// count: 1,\n// set: proxySet()\n//})\n\nstate.add(4)\nstate.delete(1)\nstate.forEach((v) => console.log(v)) // 2,3,4\n```\n\n#### `proxyMap` util\n\nThis is to create a proxy which emulate the native Map behavior. The API is the same as Map API\n\n```js\nimport { proxyMap } from 'valtio/utils'\n\nconst state = proxyMap([\n ['key', 'value'],\n ['key2', 'value2'],\n])\nstate.set('key', 'value')\nstate.delete('key')\nstate.get('key') // ---> value\nstate.forEach((value, key) => console.log(key, value)) // ---> \"key\", \"value\", \"key2\", \"value2\"\n```\n\n#### Compatibility\n\nValtio v2 works with React 18 and up.\nIt only depends on `react` and works with any\nrenderers such as `react-dom`, `react-native`, `react-three-fiber`, and so on.\n\nValtio works on Node.js, Next.js and other frameworks.\n\nValtio also works without React. See [vanilla](#use-it-vanilla).\n\n#### Plugins\n\n- [eslint-plugin-valtio](https://github.com/pmndrs/eslint-plugin-valtio)\n\n#### Recipes\n\nValtio is unopinionated about best practices.\nThe community is working on recipes.\n\n- [How to organize actions](https://github.com/pmndrs/valtio/blob/main/docs/how-tos/how-to-organize-actions.mdx)\n- [How to persist states](https://github.com/pmndrs/valtio/blob/main/docs/how-tos/how-to-persist-states.mdx)\n- [How to use with context](https://github.com/pmndrs/valtio/blob/main/docs/how-tos/how-to-use-with-context.mdx)\n- [How to split and compose states](https://github.com/pmndrs/valtio/blob/main/docs/how-tos/how-to-split-and-compose-states.mdx)\n"
},
{
"path": "docs/api/advanced/ref.mdx",
"content": "---\ntitle: 'ref'\nsection: 'API'\nsubSection: 'Advanced'\ndescription: 'Create a ref object'\n---\n\n# `ref`\n\n## A `ref` allows unproxied state in a Valtio proxy\n\nA `ref` is useful in the rare instances you need to nest an object in a `proxy` that is not wrapped in an inner proxy and, therefore, is not tracked.\n\n```js\nconst store = proxy({\n users: [\n { id: 1, name: 'Juho', uploads: ref([]) },\n ]\n })\n})\n```\n\nOnce an object is wrapped in a `ref`, it should be mutated without reassigning the object or rewrapping in a new `ref`.\n\n```js\n// ā do mutate\nstore.users[0].uploads.push({ id: 1, name: 'Juho' })\n// ā do reset\nstore.users[0].uploads.splice(0)\n\n// ā don't reassign\nstore.users[0].uploads = []\n```\n\nA `ref` should also not be used as the only state in a proxy, making the proxy usage pointless.\n\n## Codesandbox demo\n\nhttps://codesandbox.io/s/valtio-file-load-demo-oo2yzn\n"
},
{
"path": "docs/api/advanced/snapshot.mdx",
"content": "---\ntitle: 'snapshot'\nsection: 'API'\nsubSection: 'Advanced'\ndescription: 'Create a snapshot of current state'\n---\n\n# `snapshot`\n\n`snapshot` takes a proxy and returns an immutable object, unwrapped from the proxy.\n\nImmutability is achieved by _efficiently_ deep copying & freezing the object (see the [Copy on Write](#copy-on-write) section for details).\n\nBriefly, in sequential `snapshot` calls, when the values in the proxy have not changed, the previous snapshot's object reference is returned. This allows for shallow comparison in render functions, preventing spurious renders.\n\nSnapshots also throw promises, making them work with React Suspense.\n\n```js\nimport { proxy, snapshot } from 'valtio'\n\nconst store = proxy({ name: 'Mika' })\nconst snap1 = snapshot(store) // an efficient copy of the current store values, unproxied\nconst snap2 = snapshot(store)\nconsole.log(snap1 === snap2) // true, no need to re-render\n\nstore.name = 'Hanna'\nconst snap3 = snapshot(store)\nconsole.log(snap1 === snap3) // false, should re-render\n```\n\n## Copy on Write\n\nEven though snapshots are a deep copy of the entire state, they use a lazy copy-on-write mechanism for updates, so in practice they are quick to maintain.\n\nFor example, if we have a nested object of:\n\n```js\nconst author = proxy({\n firstName: 'f',\n lastName: 'l',\n books: [{ title: 't1' }, { title: 't2' }],\n})\n\nconst s1 = snapshot(author)\n```\n\nThe first `snapshot` call creates four new instances:\n\n- one for the author,\n- one for the books array, and\n- two for the book objects.\n\nWhen we mutate the 2nd book, and take a new `snapshot`:\n\n```js\nauthor.books[1].title = 't2b'\nconst s2 = snapshot(author)\n```\n\nThen `s2` will have a new copy of the 2nd book, but reuse the existing snapshot of the unchanged 1st book.\n\n```js\nconsole.log(s1 === s2) // false\nconsole.log(s1.books === s2.books) // false\nconsole.log(s1.books[0] === s2.books[0]) // true\nconsole.log(s1.books[1] === s2.books[1]) // false\n```\n\nEven though this example only reused one of the four existing snapshot instances, it shows that the cost of maintaining snapshots is based on the _depth_ of your state tree (which is typically low, like author to book to book reviews is three levels), and not the _breadth_ (1000s of books).\n\n## Classes\n\nSnapshots maintain the original objects' prototypes, so methods and getters work, and correctly evaluate against the snapshot's frozen state.\n\n```js\nimport { proxy, snapshot } from 'valtio'\n\nclass Author {\n firstName = 'f'\n lastName = 'l'\n fullName() {\n return `${this.firstName} ${this.lastName}`\n }\n}\n\nconst state = proxy(new Author())\nconst snap = snapshot(state)\n\n// the snapshot has the Author prototype\nconsole.log(snap instanceof Author) // true\n\nstate.firstName = 'f2'\n\n// Invocations use the snapshot's state, e.g. this is still 'f' because\n// inside `fullName`, `this` will be the frozen snapshot instance and not\n// the mutable state proxy\nconsole.log(snap.fullName()) // 'f l'\n```\n\nNote that the results of getters and methods are not cached, and are re-evaluated on every call.\n\nThis should be fine, because the expectation is that they execute very quickly (faster than the overhead of caching them would be worth) and are also deterministic, so the return value is based only on the already-frozen snapshot state.\n\n## Vanilla JavaScript\n\nIn VanillaJS, `snapshot` is not necessary to access proxied object values, inside or outside of subscribe. However, it is useful, for example, to keep a serializable list of un-proxied objects or check if objects have changed. It also resolves promises.\n\n \n\n
\nš” Tip\n\nIf you are using valtio outside of react, import from `valtio/vanilla`\n\n```js\nimport { proxy, snapshot } from 'valtio/vanilla'\n```\n\n
\n"
},
{
"path": "docs/api/advanced/subscribe-ops.mdx",
"content": "---\ntitle: 'subscribe-ops'\nsection: 'API'\nsubSection: 'Advanced'\ndescription: 'Fine-grained mutation tracking with operational transformations (Ops)'\n---\n\n# Subscribe Ops\n\nBy default, Valtio's `subscribe` notify you that _something_ has changed in the state proxy. However, you can opt-in to receiving **Ops** (Operations), which are detailed descriptions of exactly what was modified.\n\n## What are Ops?\n\nOps are granular mutation records. When a proxy is updated, Valtio can generate a description of the change as a tuple.\n\n### Op Types\n\n- **`set`**: `[op: 'set', path: Path, value: unknown, prevValue: unknown]`\n - Triggered when a property is assigned a new value.\n- **`delete`**: `[op: 'delete', path: Path, prevValue: unknown]`\n - Triggered when a property is deleted.\n- **`resolve`**: `[op: 'resolve', path: Path, value: unknown]`\n - Triggered when a promise in the state is fulfilled.\n- **`reject`**: `[op: 'reject', path: Path, error: unknown]`\n - Triggered when a promise in the state is rejected.\n\nThe `Path` is an array of strings or symbols representing the nested location of the property (e.g., `['user', 'profile', 'name']`).\n\n## How to use Ops\n\nThe \"ops\" feature is an **opt-in** feature because it introduces a small performance overhead for tracking and allocating these operation objects.\n\n### 1. Enabling Ops\n\nYou must explicitly enable op-tracking using the unstable API:\n\n```javascript\nimport { unstable_enableOp } from 'valtio'\n\n// Enable globally\nunstable_enableOp(true)\n```\n\n### 2. Receiving Ops in `subscribe`\n\nOnce enabled, the `subscribe` callback receives an array of these operations as its first argument.\n\n```javascript\nimport { proxy, subscribe, unstable_enableOp } from 'valtio'\n\nunstable_enableOp(true)\n\nconst state = proxy({ count: 0, text: 'hello' })\n\nsubscribe(state, (ops) => {\n ops.forEach((op) => {\n const [action, path, value, prevValue] = op\n console.log(`Action: ${action} at ${path.join('.')}`)\n console.log(`New value:`, value)\n console.log(`Previous value:`, prevValue)\n })\n})\n\nstate.count++\n// Output:\n// Action: set at count\n// New value: 1\n// Previous value: 0\n```\n\n> **Note**: If `unstable_enableOp(true)` is not called, the `ops` argument will be an empty array or `undefined`.\n\n## Use Cases\n\nWhile standard `subscribe` is sufficient for most React UI updates, Ops are useful for specific advanced scenarios:\n\n1. **Network Synchronization**: Instead of sending the entire state over the wire, you can send only the `ops` (patches). This significantly reduces bandwidth consumption in distributed applications.\n2. **Undo/Redo History**: Use the `prevValue` provided in `set` and `delete` ops to easily revert state changes.\n3. **Audit Logs & Debugging**: Track a sequence of user-driven mutations for analytics or time-travel debugging.\n4. **Devtools Integration**: Powering custom development tools that need to visualize state transitions.\n\n## Performance Considerations\n\nEnabling Ops has a small overhead cost. For every mutation, Valtio must:\n\n- Detect the change type.\n- Construct the `Path` array.\n- Allocate the `Op` tuple.\n\nIn high-frequency update scenarios (e.g., animations, canvas interactions moving hundreds of objects per frame), this can lead to:\n\n- Increased garbage collection (GC) pressure due to object allocations.\n- A measurable drop in frame rates (FPS).\n\n**Recommendation**: Only enable `unstable_enableOp` if your application actually consumes the granular `ops` data.\n"
},
{
"path": "docs/api/advanced/subscribe.mdx",
"content": "---\ntitle: 'subscribe'\nsection: 'API'\nsubSection: 'Advanced'\ndescription: 'Subscribe to a current state/object'\n---\n\n# `subscribe`\n\n## Subscribe from anywhere\n\nYou can access state outside your components and subscribe to changes.\n\n```jsx\nimport { proxy, subscribe } from 'valtio'\n\nconst state = proxy({ count: 0 })\n\n// Subscribe to all changes to the state proxy (and its child proxies)\nconst unsubscribe = subscribe(state, () =>\n console.log('state has changed to', state),\n)\n// Unsubscribe by calling the result\nunsubscribe()\n```\n\nYou can also subscribe to a portion of state.\n\n```jsx\nconst state = proxy({ obj: { foo: 'bar' }, arr: ['hello'] })\n\nsubscribe(state.obj, () => console.log('state.obj has changed to', state.obj))\nstate.obj.foo = 'baz'\nsubscribe(state.arr, () => console.log('state.arr has changed to', state.arr))\nstate.arr.push('world')\n```\n\n## Codesandbox demo in VanillaJS\n\nhttps://codesandbox.io/s/valtio-photo-booth-demo-forked-xp8hs?file=/src/main.js\n\n## Advanced: Listening to \"Ops\"\n\nThe `subscribe` callback can also receive **Ops** (Operations), which are detailed records of exactly what changed (e.g., which property was set or deleted). This is useful for advanced scenarios like synchronization or undo/redo.\n\nBecause tracking these operations has a small performance cost, they are disabled by default. For more details on how to enable and use them, check out [Subscribe Ops](./subscribe-ops).\n"
},
{
"path": "docs/api/basic/proxy.mdx",
"content": "---\ntitle: 'proxy'\nsection: 'API'\nsubSection: 'Basic'\ndescription: 'Create a proxy object.'\n---\n\n# `proxy`\n\nThe `proxy` tracks changes to the original object and all nested objects, notifying listeners when an object is modified.\n\n```js\nimport { proxy } from 'valtio'\n\nconst state = proxy({ count: 0, text: 'hello' })\n```\n\n## Mutate from anywhere\n\nYou can make changes to it in the same way you would to a normal js-object.\n\n```js\nsetInterval(() => {\n ++state.count\n}, 1000)\n```\n\n## Optimizations: noop and batching\n\nUpdates that set the value of a property to the same value are ignored. Subscribers will not be informed of a version change.\n\n```js\nconst state = proxy({ count: 0 })\n\nstate.count = 0 // has no effect\n```\n\nMultiple changes in the same event loop tick will be batched together. Subscribers will be notified of a single version change.\n\n```js\nconst state = proxy({ count: 0, text: 'hello' })\n// subscribers will be notified once after both mutations\nstate.count = 1\nstate.text = 'world'\n```\n\n## Nested proxies\n\nProxies can be nested in other `proxy` objects and updated as a whole.\n\n```jsx\nimport { proxy, useSnapshot } from 'valtio'\n\nconst personState = proxy({ name: 'Timo', role: 'admin' })\nconst authState = proxy({ status: 'loggedIn', user: personState })\n\nauthState.user.name = 'Nina'\n```\n\n## Promises in proxies\n\nSee [`async`](../../guides/async) for more details.\n\n```jsx\nimport { proxy } from 'valtio'\n\nconst bombState = proxy({\n explosion: new Promise((resolve) => setTimeout(() => resolve('Boom!'), 3000)),\n})\n```\n\n## Gotchas\n\nIf you reassign the proxy to an entirely new object, it will stop working because you are replacing the proxied object with a new object reference.\n\n```jsx\nlet state = proxy({ user: { name: 'Timo' } })\n\nsubscribe(state, () => {\n console.log(state.user.name)\n})\n// will not notify subscribers\nstate = { user: { name: 'Nina' } }\n\n// instead\nlet state = proxy({ user: { name: 'Timo' } })\n\nsubscribe(state, () => {\n console.log(state.user.name) // logs \"Nina\"\n})\n// will notify subscribers\nstate.user.name = 'Nina'\n```\n\nNot everything can be proxied. Generally, you are safe if it is serializable. Classes can also be proxied. But avoid special objects.\n\n```jsx\n// these won't work - changes to these objects won't cause updates\n// to store state that is unproxied see the docs on ref\nconst state = proxy({\n chart: d3.select('#chart'),\n component: React.createElement('div'),\n map: new Map(), // see proxyMap\n storage: localStorage,\n})\n\n// this will work\nclass User {\n first = null\n last = null\n constructor(first, last) {\n this.first = first\n this.last = last\n }\n greet() {\n return `Hi ${this.first}!`\n }\n get fullName() {\n return `${this.first} ${this.last}`\n }\n}\nconst state = proxy(new User('Timo', 'Kivinen'))\n```\n"
},
{
"path": "docs/api/basic/useSnapshot.mdx",
"content": "---\ntitle: 'useSnapshot'\nsection: 'API'\nsubSection: 'Basic'\ndescription: 'Create a local snapshot that catches changes.'\n---\n\n# `useSnapshot`\n\nCreate a local `snapshot` that catches changes.\n\nNormally, Valtio's snapshots (created via `snapshot()`) are recreated on _any_ change to a proxy, or any of its child proxies.\n\nHowever `useSnapshot` wraps the Valtio snapshot in an access-tracking proxy. This is to make sure your component is render optimized, i.e. it will only re-render if keys that it (or its child components) specifically accessed has changed, and not on every single change to the proxy.\n\n## Usage\n\n### Read from snapshots in render, use the proxy in callbacks\n\nSnapshots are read-only to render the JSX from their consistent view of the data.\n\nMutations, and also any reads in callbacks that make mutations, need to be made via the proxy, so that the callback reads & writes the latest value.\n\n```jsx\nfunction Counter() {\n const snap = useSnapshot(state)\n return (\n
\n {snap.count}\n {\n // also read from the state proxy in callbacks\n if (state.count < 10) {\n ++state.count\n }\n }}\n >\n +1\n \n
\n )\n}\n```\n\n### Parent/Child Components\n\nIf you have a parent component use `useSnapshot`, it can pass snapshots to child components and the parent & children will re-render when the snapshot changes.\n\nFor example:\n\n```jsx\nconst state = proxy({\n books: [\n { id: 1, title: 'b1' },\n { id: 2, title: 'b2' },\n ],\n})\n\nfunction AuthorView() {\n const snap = useSnapshot(state)\n return (\n
\n {snap.books.map((book) => (\n \n ))}\n
\n )\n}\n\nfunction BookView({ book }) {\n // book is a snapshot\n return
{book.title}
\n}\n```\n\nIf book 2's title is changed, a new `snap` is created and the `AuthorView` and `BookView` components will re-render.\n\nNote if `BookView` is `React.memo`d, the 1st `BookView` will not re-render, b/c the 1st `Book` snapshot will be the same instance, as only the 2nd `Book` was mutated (the root `Author` snapshot will also be updated since the list of `books` has changed).\n\n### Child Components Making Mutations\n\nThe above approach works if `BookView` is read-only; if your child component needs to make mutations, then you'll need to pass the proxy:\n\n```jsx\nfunction AuthorView() {\n const snap = useSnapshot(state)\n return (\n
\n {snap.books.map((book, i) => (\n \n ))}\n
\n )\n}\n\nfunction BookView({ book }) {\n // book is the proxy, so we can re-snap it + mutate it\n const snap = useSnapshot(book)\n return
book.updateTitle()}>{snap.title}
\n}\n```\n\nOr you can pass both the snapshot and proxy together, if you don't want to call `useSnapshot` in the child component:\n\n```jsx\nfunction AuthorView() {\n const snap = useSnapshot(state)\n return (\n
\n {snap.books.map((book, i) => (\n \n ))}\n
\n )\n}\n```\n\nThere should be no performance difference between these two approaches.\n\n### Read only what you need\n\nEvery object inside your proxy also becomes a proxy (if you don't use `ref()`). So you can also use them to create\na local snapshot.\n\n```jsx\nfunction ProfileName() {\n const snap = useSnapshot(state.profile)\n return
{snap.name}
\n}\n```\n\n## Gotchas\n\nBeware of replacing the child proxy with something else, breaking your `snapshot`. This will replace the reference of the proxy with what you assign it to which removes the proxy's traps. You can see an example below.\n\n```js\nconsole.log(state)\n{\n profile: {\n name: 'valtio'\n }\n}\nchildState = state.profile\nconsole.log(childState)\n{\n name: 'valtio'\n}\nstate.profile.name = 'react'\nconsole.log(childState)\n{\n name: 'react'\n}\nstate.profile = { name: 'new name' }\nconsole.log(childState)\n{\n name: 'react'\n}\nconsole.log(state)\n{\n profile: {\n name: 'new name'\n }\n}\n```\n\n`useSnapshot()` depends on the original reference of the child proxy so if you replace it with a new one, the component\nthat is subscribed to the old proxy won't receive new updates because it is still subscribed to the old one.\n\nIn this case, we recommend one of the approaches below. In neither example do you need to worry about re-renders because it is render-optimized.\n\n```jsx\nconst snap = useSnapshot(state)\n\nreturn
\n```\n\n## Dev Mode Debug Values\n\nIn dev mode, `useSnapshot` uses React's `useDebugValue` to output a list of fields that were accessed during rendering, i.e. which specific fields will trigger re-render when the tracking proxy changes.\n\n \n\n
\n!! There are two disclaimers to using the debug value\n\n1. Due to the way `useSnapshot` uses a proxy to recorded accesses _after_ `useSnapshot` has returned, the fields listed in `useDebugValue` are technically from the _previous_ render.\n2. Object getter and class getter calls are not included in the `useDebugValue` output, but don't worry, they are actually correctly tracked internally and correctly trigger re-renders when changed.\n\n
\n\n \n\n \n\n## Codesandbox demo\n\nhttps://codesandbox.io/s/ping-pong-with-valtio-wb25s?file=/src/App.js\n"
},
{
"path": "docs/api/hacks/getVersion.mdx",
"content": "---\ntitle: 'getVersion'\nsection: 'API'\nsubSection: 'Hacks'\ndescription: ''\n---\n\n# `getVersion`\n\nIn Valtio, updates to proxied objects are tracked internally with a version number.\n\nEvery mutation to a proxy increases a global version number, and assigns the just mutated proxy, and any parent proxies (which automatically subscribe to their child proxies), to the latest version number.\n\nThis is how `snapshot` knows whether a new snapshot is necessary: has my proxy's version number changed since the last snapshot?\n\nGiven its importance to valtio's internal behavior, the `getVersion` helper can be used to check if a proxied object has been updated, but this is not typically useful or recommended to use in application code because `snapshot` and `useSnapshot` already handle version tracking internally.\n\n```js\ngetVersion(proxyObject)\n```\n"
},
{
"path": "docs/api/hacks/internals.mdx",
"content": "---\ntitle: 'Internals'\nsection: 'API'\nsubSection: 'Hacks'\ndescription: ''\n---\n\nValtio exposes some internal capabilities.\nThis isn't for app developers. Use it at your own risk.\n\n# `unstable_getInternalStates`\n\nThis function exposes the internal states. Modifying such states may result in wrong behaviors. You need to understand the [source code](https://github.com/pmndrs/valtio/blob/main/src/vanilla.ts) thoroughly to use it.\n\n# `unstable_replaceInternalFunction`\n\nThis function exposes a way to replace some internal functions. It can easily break things. You need to understand the [source code](https://github.com/pmndrs/valtio/blob/main/src/vanilla.ts) thoroughly to use it.\n"
},
{
"path": "docs/api/utils/derive.mdx",
"content": "---\ntitle: 'derive'\nsection: 'API'\nsubSection: 'Utils'\ndescription: 'create a new proxy derived from others'\n---\n\n## `derive`\n\n> **ā ļø Deprecated**\n>\n> This package is no longer maintained. Please migrate to\n> [valtio-reactive](https://github.com/valtiojs/valtio-reactive).\n\n## Installation\n\n```bash\nnpm install derive-valtio\n```\n\n#### create a new proxy derived from others\n\nYou can subscribe to some proxies using `get` to create snapshots used to compute new values.\n\n```js\nimport { derive } from 'derive-valtio'\n\n// create a base proxy\nconst state = proxy({\n count: 1,\n})\n\n// create a derived proxy\nconst derived = derive({\n doubled: (get) => get(state).count * 2,\n})\n\n// alternatively, attach derived properties to an existing proxy\nderive(\n {\n tripled: (get) => get(state).count * 3,\n },\n {\n proxy: state,\n },\n)\n```\n\n## `underive`\n\n## Stop evaluating\n\nIn some cases you may want to unsubscribe after deriving a proxy. To do so, use the `underive` util. You may also pass keys to indicate which properties you want to unsubscribe. If you specify `delete` option, it will delete the properties\nand you can attach new derived properties.\n\n```js\nimport { derive, underive } from 'derive-valtio'\nconst state = proxy({\n count: 1,\n})\n\nconst derivedState = derive({\n doubled: (get) => get(state).count * 2,\n})\n\nunderive(derivedState)\n```\n\n## Usage patterns\n\n### Re-computes when unrelated properties change\n\nWith `derive`, the computation will occur if any property of the base proxy changes. Example:\n\n```javascript\nconst baseProxy = proxy({\n counter1: 0,\n counter2: 0,\n counter3: 0,\n counter4: 0,\n})\n\nconst countersOneAndTwoSelectors = derive({\n sum: (get) => get(baseProxy).counter1 + get(baseProxy).counter2,\n})\n```\n\nIn this example if `baseProxy.counter3` or `baseProxy.counter4` are changed, `countersOneAndTwoSelectors` will re-compute all of the keys in it.\n\n### `get` sub-objects due to update of unrelated proxies on parent proxy\n\nAs noted on this page, re-computation occurs when unrelated properties change. It is possible to use `get` on sub-objects. This has the benefit of not re-computing when properties of the parent object are updated. Example:\n\n```javascript\nconst baseProxy = proxy({\n counter1And2: {\n counter1: 0,\n counter2: 0,\n },\n counter3: 0,\n counter4: 0,\n})\n\nconst countersOneAndTwoSelectors = derive({\n sum: (get) =>\n get(baseProxy.counter1And2).counter1 + get(baseProxy.counter1And2).counter2,\n})\n```\n\nNow even if `counter3` and `counter4` are updated, it will not cause re-computation of `countersOneAndTwoSelectors`.\n"
},
{
"path": "docs/api/utils/devtools.mdx",
"content": "---\ntitle: 'devtools'\nsection: 'API'\nsubSection: 'Utils'\ndescription: 'Use the Redux DevTools extension with Valtio'\n---\n\n# devtools\n\n#### Dev tools\n\nYou can use [Redux DevTools Extension](https://github.com/reduxjs/redux-devtools) for plain objects and arrays.\n\n```jsx\nimport { devtools } from 'valtio/utils'\n\nconst state = proxy({ count: 0, text: 'hello' })\nconst unsub = devtools(state, { name: 'state name', enabled: true })\n```\n\n\n Manipulating state with Redux DevTools\nThe 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.\n\n\n\n\n#### Use it with vanilla JS\n\nValtio is not tied to React, you can use it in vanillaJS.\n\n```jsx\nimport { proxy, subscribe, snapshot } from 'valtio/vanilla'\n\nconst state = proxy({ count: 0, text: 'hello' })\n\nsubscribe(state, () => {\n console.log('state is mutated')\n const obj = snapshot(state) // A snapshot is an immutable object\n})\n```\n\n#### Use it with TypeScript\n\nIt's recommended to install and import types from `@redux-devtools/extension` to get types correctly.\n\n```ts\nimport type {} from '@redux-devtools/extension'\nimport { devtools } from 'valtio/utils'\n```\n"
},
{
"path": "docs/api/utils/proxyMap.mdx",
"content": "---\ntitle: 'proxyMap'\nsection: 'API'\nsubSection: 'Utils'\ndescription: ''\n---\n\n# `proxyMap`\n\n## Reasoning\n\nNative `Maps` store their data in internal slots which are not observable. This means that `valtio` cannot track changes to the data inside of a native `Map`. `proxyMap` is a utility that allows you to create a proxy that mimics the behavior of a `Map` while still allowing valtio to track changes to the data.\n\n## When to use `proxyMap`\n\n`proxyMap` is useful when you need the flexibility of a `Map` but still want to track changes to the data. It can be useful if you don't know the structure of the data you'll be working with and this data may have non-primitive values as keys (e.g. objects, arrays, etc.). In this case, you can use `proxyMap` to create a proxy that mimics the behavior of a `Map` while still allowing valtio to track changes to the data. If your data can be represented as a simple object, you should use `proxy` with a simple object instead. It is more performant and easier to use.\n\n## Use a js Map with Valtio\n\nThis utility creates a proxy which mimics the native Map behavior. The API is the same as the Map API.\n\n```js\nimport { proxyMap } from 'valtio/utils'\n\nconst state = proxyMap()\nstate.size // ---> 0\n\nstate.set(1, 'hello')\nstate.size // ---> 1\n\nstate.delete(1)\nstate.size // ---> 0\n```\n\n## Nesting\n\nIt can be used inside a `proxy` as well.\n\n```js\nimport { proxyMap } from 'valtio/utils'\n\nconst state = proxy({\n count: 1,\n map: proxyMap(),\n})\n```\n\nWhen using an object as a key, you can wrap it with `ref` so it's not proxied. This is useful if you want to preserve the key equality\n\n```js\nimport { proxyMap } from 'valtio/utils'\n\n// with ref\nconst key = ref({})\nstate.set(key, 'hello')\nstate.get(key) //hello\n\n// without ref\nconst key = {}\nstate.set(key, 'value')\nstate.get(key) //undefined\n```\n\n## `isProxyMap`\n\nIf you want to check if an object is a proxyMap, you can use the `isProxyMap` function.\n\n```js\nimport { proxy, ref } from 'valtio'\nimport { proxyMap, isProxyMap } from 'valtio/utils'\n\nconst state = proxy({\n nativeMap: ref(new Map(/*...*/)),\n proxyMap: proxyMap(),\n})\n\nisProxyMap(state.nativeMap) // false\nisProxyMap(state.proxyMap) // true\n```\n\n## Codesandbox demo\n\nhttps://codesandbox.io/s/github/pmndrs/valtio/tree/main/examples/todo-with-proxyMap\n"
},
{
"path": "docs/api/utils/proxySet.mdx",
"content": "---\ntitle: 'proxySet'\nsection: 'API'\nsubSection: 'Utils'\ndescription: ''\n---\n\n# `proxySet`\n\n## Reasoning\n\nNative `Sets` store their data in internal slots which are not observable. This means that `valtio` cannot track changes to the data inside of a native `Set`. `proxySet` is a utility that allows you to create a proxy that mimics the behavior of a `Set` while still allowing valtio to track changes to the data.\n\n## When to use `proxySet`\n\n`proxySet` is useful when you need the functionality of a `Set` but still want to track changes to the data. `proxySet` can be useful if you're wanting to store unique values or if you want to perform mathematical `Set` operations on the data, such as union, intersection, or difference. `proxySet` supports all of the new methods introduced to `Set`:\n\n- `intersection`\n- `union`\n- `difference`\n- `symmetricDifference`\n- `isSubsetOf`\n- `isSupersetOf`\n- `isDisjointFrom`\n\nYou can see a full list of the methods supported by `proxySet` in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).\n\nIf your data can be represented as a simple array or object, and you have no need for the additional functionality provided by `proxySet`, you should use `proxy` with a simple array or object instead. It is more performant and easier to use.\n\n## Use a js `Set` with Valtio\n\nThis utility creates a proxy which mimics the native `Set` behavior. The API is the same as the native `Set` API.\n\n```js\nimport { proxySet } from 'valtio/utils'\n\nconst state = proxySet([1, 2, 3])\n\nstate.add(4)\nstate.delete(1)\nstate.forEach((v) => console.log(v)) // ---> 2,3,4\n```\n\n## Nesting\n\nIt can be used inside a `proxy` as well.\n\n```js\nimport { proxySet } from 'valtio/utils'\n\nconst state = proxy({\n count: 1,\n set: proxySet(),\n})\n```\n\n## `isProxySet`\n\nIf you want to check if an object is a proxyMap, you can use the `isProxySet` function.\n\n```js\nimport { proxy, ref } from 'valtio'\nimport { proxySet, isProxySet } from 'valtio/utils'\n\nconst state = proxy({\n nativeSet: ref(new Set(/*...*/)),\n proxySet: proxySet(),\n})\n\nisProxySet(state.nativeSet) // false\nisProxySet(state.proxySet) // true\n```\n"
},
{
"path": "docs/api/utils/proxyWithHistory.mdx",
"content": "---\ntitle: 'proxyWithHistory'\nsection: 'API'\nsubSection: 'Utils'\ndescription: ''\n---\n\n# `proxyWithHistory`\n\n## Keep a history of snapshots\n\nThis is a utility function to create a proxy with snapshot history.\n\n```js\nimport { proxyWithHistory } from 'valtio-history'\n\nconst state = proxyWithHistory({ count: 0 })\nconsole.log(state.value) // ---> { count: 0 }\nstate.value.count += 1\nconsole.log(state.value) // ---> { count: 1 }\nstate.undo()\nconsole.log(state.value) // ---> { count: 0 }\nstate.redo()\nconsole.log(state.value) // ---> { count: 1 }\n```\n\n## Codesandbox demo\n\nhttps://codesandbox.io/s/valtio-history-example-v0-m353xc?file=/src/App.tsx\n"
},
{
"path": "docs/api/utils/subscribeKey.mdx",
"content": "---\ntitle: 'subscribeKey'\nsection: 'API'\nsubSection: 'Utils'\ndescription: ''\n---\n\n# `subscribeKey`\n\nTo subscribe to a primitive value in proxy state, consider `subscribeKey`.\n\n```js\nimport { subscribeKey } from 'valtio/utils'\n\nconst state = proxy({ count: 0, text: 'hello' })\nsubscribeKey(state, 'count', (v) =>\n console.log('state.count has changed to', v),\n)\n```\n\n## Codesandbox demo\n\nhttps://codesandbox.io/s/dynamic-ui-with-valtio-9gme46?file=/src/ComplexCounter.tsx\n"
},
{
"path": "docs/api/utils/unstable_deepProxy.mdx",
"content": "---\ntitle: 'unstable_deepProxy'\nsection: 'API'\nsubSection: 'Utils'\ndescription: ''\n---\n\n# `unstable_deepProxy`\n\nYou can use this utility to recursively go through an object and proxy all proxiable objects with the exception of anything marked with `ref()`. `Map`s will become `proxyMap`s and `Set`s will become `proxySet`s.\n\n```js\nimport {\n unstable_deepProxy as deepProxy,\n isProxyMap,\n isProxySet,\n} from 'valtio/utils'\n\nconst obj = {\n mySet: new Set(),\n myMap: new Map(),\n sub: {\n foo: 'bar',\n },\n}\n\nconst clonedProxy = deepProxy(obj)\n\nconsole.log(isProxyMap(clonedProxy.myMap)) // true\nconsole.log(isProxySet(clonedProxy.mySet)) // true\n```\n"
},
{
"path": "docs/api/utils/watch.mdx",
"content": "---\ntitle: 'watch'\nsection: 'API'\nsubSection: 'Utils'\ndescription: 'watch for changes.'\n---\n\n# `watch`\n\n> **ā ļø Deprecated**\n>\n> This util is no longer maintained. Please migrate to\n> [valtio-reactive](https://github.com/valtiojs/valtio-reactive).\n\n## Subscription via a getter\n\nThis utility supports subscribing to multiple proxy objects (unlike `subscribe` which listens to only a single proxy). Proxy objects are subscribed with a `get` function passed to the callback.\n\nAny changes to the proxy object (or its child proxies) will rerun the callback.\n\nAlso note the callback will run once immediately when `watch` is called, even if the proxies have not been yet mutated, to establish the initial subscriptions.\n\n```js\nimport { proxy } from 'valtio'\nimport { watch } from 'valtio/utils'\n\nconst userState = proxy({ user: { name: 'Juuso' } })\nconst sessionState = proxy({ expired: false })\n\nwatch((get) => {\n // `get` adds `sessionState` to this callback's watched proxies\n get(sessionState)\n const expired = sessionState.expired\n // Or call it inline\n const name = get(userState).user.name\n console.log(`${name}'s session is ${expired ? 'expired' : 'valid'}`)\n})\n// 'Juuso's session is valid'\nsessionState.expired = true\n// 'Juuso's session is expired'\n```\n\n## Cleanup\n\nYou may return a cleanup function that runs both:\n\n- Before each re-invocation of the callback (i.e. due to a watched proxy changing)\n- When the `watch` itself is stopped (by calling the cleanup function returned by `watch`)\n\n```js\nwatch((get) => {\n const expired = get(sessionState).expired\n const name = get(userState).user.name\n console.log(`${name}'s session is ${expired ? 'expired' : 'valid'}`)\n return () => {\n if (expired) {\n console.log('Cleaning up')\n }\n }\n})\n// Output from 1st immediate invocation of the callbcak\n// 'Juuso's session is valid'\n\n// Changing a dependency will invoke the cleanup callback first,\n// but the captured `expired` is false, so we only see output from the\n// 2nd invocation of the callback.\nsessionState.expired = true\n// 'Juuso's session is expired'\n\n// Changing a dependency will again invoke the cleanup callback,\n// and `expired` is true now, so we output from both our cleanup\n// function as well as the 3rd invocation of the callback.\nsetTimeout(() => {\n userState.user.name = 'Anonymous'\n}, 200)\n// 200ms -> 'Anonymous's session is expired'\n// 'Cleaning up' logged\n```\n\n## Gotchas\n\nIf you remove the setTimeout in the example above, `'Juuso's session is expired'` will become `'Anonymous's session is expired'` and it will be logged twice. Valtio will batch updates by default. You may pass `{sync: true}` as a second argument to `watch` to disable batching.\n\n## No usage tracking\n\n`watch` currently does not implement the usage tracking of `useSnapshot`, so the callback will rerun anytime a watched proxy (or child proxy) has any fields mutated, regardless of the fields accessed within the `callback`'s code.\n\nAnd the return value of `get` is just the proxy itself, not a snapshot.\n\nThis is because `watch` is a vanilla primitive built on top of `subscribe`. It is potentially possible for `watch`, or a new `watch`-like method, to implement usage tracking in the future, see [this discussion](https://github.com/pmndrs/valtio/discussions/640) if interested.\n"
},
{
"path": "docs/guides/async.mdx",
"content": "---\ntitle: 'Async'\nsection: 'Advanced'\ndescription: 'Working with promises and Suspense'\n---\n\n# `async`\n\n## Promises\n\nPromises may be values in a proxied object. They will be resolved in calls to `snapshot`.\n\n```jsx\n// vanillajs example\nconst countDiv: HTMLElement | null = document.getElementById('count')\nif (countDiv) countDiv.innerText = '0'\n\nconst store = proxy({\n count: new Promise((r) => setTimeout(() => r(1), 1000)),\n})\n\nsubscribe(store, () => {\n const value = snapshot(store).count\n if (countDiv && typeof value === 'number') {\n countDiv.innerText = String(value)\n store.count = new Promise((r) => setTimeout(() => r(value + 1), 1000))\n }\n})\n```\n\n## Suspend your React components\n\nValtio is compatible with React 19 `use` hook. 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.\n\n```jsx\nimport { use } from 'react' // React 19\n// import { use } from 'react18-use' // React 18\n\nconst state = proxy({ post: fetch(url).then((res) => res.json()) })\n\nfunction Post() {\n const snap = useSnapshot(state)\n return
{use(snap.post).title}
\n}\n\nfunction App() {\n return (\n \n \n \n )\n}\n```\n\nIt still suffers from \"de-opt\", which prevents `useTransition` to work well. To mitigate it, there is a third-party library [use-valtio](https://github.com/valtiojs/use-valtio).\n\n## Codesandbox Pokemon fetch demo\n\nhttps://codesandbox.io/s/valtio-pokemon-fetch-x1lkbj?file=/src/App.tsx\n\n## Codesandbox auth demo\n\nhttps://codesandbox.io/s/valtio-async-1pstl1?file=/src/App.tsx\n"
},
{
"path": "docs/guides/component-state.mdx",
"content": "---\ntitle: 'Component State'\nsection: 'Advanced'\ndescription: 'Isolate component state with useRef'\n---\n\n# Component State\n\nTo isolate component state for reusability, Valtio must live in the React lifecycle. You can wrap a `proxy` in a ref, passing it with props or context.\n\n```jsx\nimport { createContext, useContext } from 'react'\nimport { proxy, useSnapshot } from 'valtio'\n\nconst MyContext = createContext()\n\nconst MyProvider = ({ children }) => {\n const state = useRef(proxy({ count: 0 })).current\n return {children}\n}\n\nconst MyCounter = () => {\n const state = useContext(MyContext)\n const snap = useSnapshot(state)\n return (\n <>\n {snap.count} \n \n )\n}\n```\n\n## Codesandbox example\n\nhttps://codesandbox.io/s/valtio-component-ye5tbg?file=/src/App.tsx\n\n## Alternatives\n\nIf you are not happy with `useRef` usage, consider:\n\n- [use-constant](https://www.npmjs.com/package/use-constant)\n- [bunshi](https://www.bunshi.org/recipes/valtio/)\n- You may also create custom hooks wrapping useContext and optionally useSnapshot.\n\n### Bunshi example\n\nhttps://codesandbox.io/s/77r53c?file=/molecules.ts\n"
},
{
"path": "docs/guides/computed-properties.mdx",
"content": "---\ntitle: 'Computed Properties'\nsection: 'Advanced'\ndescription: 'Use object getters and setters'\n---\n\n# Computed Properties\n\nIn Valtio you can use object & class getters and setters to create computed properties.\n\n \n\n
\nā¹ļø Note\n\nGetters in JavaScript are a more advanced feature of the language, so Valtio recommends using them with caution. That said, if you are a more advanced JavaScript programmer, they should work as you expect; see the \"Note about using `this`\" section below.\n\n
\n \n\n \n\n## Simple object getter\n\n```js\nconst state = proxy({\n count: 1,\n get doubled() {\n return this.count * 2\n },\n})\nconsole.log(state.doubled) // 2\n\n// Getter calls on the snapshot work as expected\nconst snap = snapshot(state)\nconsole.log(snap.doubled) // 2\n\n// When count changes in the state proxy\nstate.count = 10\n// Then snapshot's computed property does not change\nconsole.log(snap.doubled) // 2\n```\n\nWhen you call `state.doubled` on the `state` proxy, it is not cached, and will be re-calculated on every call (if you must cache this result, see the section below on `proxy-memoize`).\n\nHowever, when you make a snapshot, calls to `snap.doubled` are effectively cached, because the value of an object getter is copied during the snapshot process.\n\n \n\n
\nā¹ļø Note\n\nIn the current implementation a computed property should only reference \\*\\*\\_sibling\\*\\*\\* properties, otherwise you'll encounter weird bugs. For example:\n\n
\n\n \n\n```js\nconst user = proxy({\n name: 'John',\n // OK - can reference sibling props via `this`\n get greetingEn() {\n return 'Hello ' + this.name\n },\n})\n```\n\n```js\nconst state = proxy({\n // could be nested\n user: {\n name: 'John',\n // OK - can reference sibling props via `this`\n get greetingEn() {\n return 'Hello ' + this.name\n },\n },\n})\n```\n\n```js\nconst state = proxy({\n user: {\n name: 'John',\n },\n greetings: {\n // WRONG - `this` points to `state.greetings`.\n get greetingEn() {\n return 'Hello ' + this.user.name\n },\n },\n})\n```\n\n```js\nconst user = proxy({\n name: 'John',\n})\nconst greetings = proxy({\n // WRONG - `this` points to `greetings`.\n get greetingEn() {\n return 'Hello ' + this.name\n },\n})\n```\n\nA workaround to it is to attach the related object as a property.\n\n```js\nconst user = proxy({\n name: 'John',\n})\nconst greetings = proxy({\n user, // attach the `user` proxy object\n // OK - can reference user props via `this`\n get greetingEn() {\n return 'Hello ' + this.user.name\n },\n})\n```\n\nAnother method would be to create a separate proxy and\nsynchronize with `subscribe`.\n\n```js\nconst user = proxy({\n name: 'John',\n})\nconst greetings = proxy({\n greetingEn: 'Hello ' + user.name,\n})\nsubscribe(user, () => {\n greetings.greetingEn = 'Hello ' + user.name\n})\n```\n\nOr with `watch`.\n\n```js\nconst user = proxy({\n name: 'John',\n})\nconst greetings = proxy({})\nwatch((get) => {\n greetings.greetingEn = 'Hello ' + get(user).name\n})\n```\n\n## Object getter and setter\n\nSetters are also supported:\n\n```js\nconst state = proxy({\n count: 1,\n get doubled() {\n return state.count * 2\n },\n set doubled(newValue) {\n state.count = newValue / 2\n },\n})\n\n// Setter calls on the state work as expected\nstate.doubled = 4\nconsole.log(state.count) // 2\n\n// Getter calls on the snapshot work as expected\nconst snap = snapshot(state)\nconsole.log(snap.doubled) // 4\n\n// And setter calls on the snapshot fail as expected\n// compile error: Cannot assign to 'doubled' because it is a read-only property.\n// runtime error: TypeError: Cannot assign to read only property 'doubled' of object '#
![\"valtio\"](\"logo.svg\")
\n![\"image\"](\"https://user-images.githubusercontent.com/6372489/141134955-26e9ffce-1e2a-4c8c-a9b3-d9da739610fe.png\")
\n![\"image\"](\"https://user-images.githubusercontent.com/6372489/141134955-26e9ffce-1e2a-4c8c-a9b3-d9da739610fe.png\"/)
\n