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.
Objects and arrays
Section titled “Objects and arrays”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.
Create parent values first
Section titled “Create parent values first”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.
Prefer a path to the exact value
Section titled “Prefer a path to the exact value”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.