valtio-select - utility for structural changes and nullable proxies

[paol-imi]

Hey Valtio community,

First, a big thank you to the maintainers and everyone here. The library is excellent, and the existing discussions and resources have been incredibly helpful for learning and building with it.

While working on a project, I ran into a couple of common scenarios where useSnapshot can be tricky:

1. Nullable Proxies: Passing a proxy that is null or undefined to useSnapshot (e.g., useSnapshot(state.user) when user is null) throws an error.
2. Structural Changes: Subscribing to a nested object (useSnapshot(state.user)) doesn't update the component if the user object itself is later replaced with a new one.

To address these points, I created a small companion library, valtio-select. It introduces a single hook, useTrackedSnapshot, which uses a selector function to create smarter subscriptions that automatically adapt to these cases.

Here is a quick example that solves both problems at once:

import { proxy } from 'valtio'
import { useTrackedSnapshot } from 'valtio-select'

// State where the user can be null
const state = proxy({
  user: null as { name: string } | null,
})

function UserDisplay() {
  // 1. Selector gracefully handles the null case using optional chaining.
  // 2. It tracks the `user` property on `state`.
  const name = useTrackedSnapshot(state, (s) => s.user?.name ?? 'Guest')
  return <div>User: {name}</div>
}

// Later, we perform a structural change by assigning a new object.
function logInUser() {
  state.user = { name: 'Jane' }
  // The UserDisplay component will correctly update from 'Guest' to 'Jane'.
}

The hook works by tracking exactly which properties are accessed in the selector. If any of them change, it re-runs the tracking and rebuilds the subscriptions, so it never has stale references.

It also provides:

• Fine-grained re-renders based on the selector's return value.
• The core logic is also available as a non-React subscribeTracked function.

There are surely multiple possible solutions to these challenges, but I aimed for an approach that felt simple, effective, and true to the minimal spirit of Valtio. A key goal was to ensure it's fully compatible with any existing codebase, allowing you to adopt it for specific components without needing to change your state structure or anything else.

I built this to hopefully give back a little to the ecosystem and would love any feedback. You can find the library here:

Repo Link: https://github.com/ts-zen/valtio-select

[overthemike]

Very nice! I'll definitely take a look.

[dai-shi]

I like the impl style that depends only on public api.