API reference
native-state-react exports three named APIs: Root, useNativeState, and useNativeSelector.
import { Root, useNativeState, useNativeSelector } from 'native-state-react';<Root>
Section titled “<Root>”Initializes the module-level store on its first render and returns its children.
| Prop | Type | Default | Description |
|---|---|---|---|
initial |
object | {} |
Initial root state. Used only by the first <Root> initialization in the current module instance. |
children |
React node | null |
Content to render. |
<Root initial={{ user: { name: 'Mary' } }}> <App /></Root>Use one <Root> at the top of the app. It does not create a store per component tree or reset the store when it renders again.
useNativeState(path, initialValue?)
Section titled “useNativeState(path, initialValue?)”Subscribes to a path and returns a tuple containing its snapshot and a setter:
const [value, setValue] = useNativeState(path, initialValue?);| Argument | Type | Description |
|---|---|---|
path |
string | A path such as 'state.user.name' or 'state.todos[0].done'. |
initialValue |
any, optional | Schedules this value to be written after render when it is not undefined. It is not a “use only if missing” default. |
The setter accepts a direct value. It does not implement React’s functional updater form:
const [name, setName] = useNativeState('state.user.name');setName('George');For nested paths, the parent object or array must already exist. Root-level slice setters replace that property; nested writes update the existing parent in place. See object identity and nested writes.
useNativeSelector(selector)
Section titled “useNativeSelector(selector)”Subscribes to a selected value and returns its snapshot:
const value = useNativeSelector(selector);| Argument | Type | Description |
|---|---|---|
selector |
string | function | A path string such as 'state.user.name', or a function receiving the root state and returning a value. |
Path selectors receive path-based notifications. Function selectors are notified for every store update. In both cases, React compares snapshots; prefer selecting stable values.
TypeScript
Section titled “TypeScript”The package currently ships JavaScript without TypeScript declaration files. TypeScript users may need to add their own local declarations or use a package release that includes types.