Skip to content

State paths

A state path identifies a value in the shared store. Use state. as the root prefix, then separate object properties with dots.

State value Path
state.user.name 'state.user.name'
state.settings.theme 'state.settings.theme'
state.todos[0].done 'state.todos[0].done'

Use state. consistently for every path.

For object properties, add a dot and the property name. For array entries, use a numeric bracket index:

const [theme, setTheme] = useNativeState('state.settings.theme');
const [firstTodo, setFirstTodo] = useNativeState('state.todos[0].title');

The path parser supports numeric bracket notation such as [0]. It does not provide quoted bracket notation for property names containing dots or other special characters.

Every parent along a nested path must already exist when you write to that path. The library does not create missing objects or arrays automatically.

// This initial state provides every parent used below.
<Root initial={{ todos: [{ title: 'Read the docs', done: false }] }}>
<Todo />
</Root>
function Todo() {
const [done, setDone] = useNativeState('state.todos[0].done');
return <button onClick={() => setDone(!done)}>{done ? 'Done' : 'Mark done'}</button>;
}

If todos or its first item is missing, a nested write cannot proceed and throws an error. Add the required shape to <Root initial> before using the path.

Subscribe to the smallest value a component needs. For example, use 'state.user.name' to display a name rather than subscribing to the whole user object. This makes the selected snapshot easier to reason about and avoids relying on object identity after a nested update.

See selector behavior for more about snapshot comparisons.