Skip to content

API reference

native-state-react exports three named APIs: Root, useNativeState, and useNativeSelector.

import { Root, useNativeState, useNativeSelector } from 'native-state-react';

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.

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.

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.

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.