react-iten

React bindings for iten, an ultralight typed in-memory router for embedded JavaScript apps.

Use this package when you want iten route state and React hooks/components without Jotai. Use jotai-iten when router context or guards should read Jotai atoms directly.

Install

npm install react-iten react

react-iten depends on iten-core. Install @tanstack/react-query only when route loaders call queryClient.ensureQueryData, and install zod only when using react-iten/zod.

Quick Start

import {
  createRoute,
  createRouter,
  defineRoutes,
  type InferRoutes,
  route,
} from 'react-iten'

const routes = defineRoutes({
  home: route(),
  project: route<{ id: string }>(),
  settings: route(),
})

type Routes = InferRoutes<typeof routes>

const toRoute = createRoute(routes)

const router = createRouter<Routes>({
  initial: toRoute({ name: 'home' }),
})

export const { Link, Navigate, Route, Switch, useNavigate, useRoute } = router

<Switch>
  <Route name="home">{() => <Home />}</Route>
  <Route name="project">{({ id }) => <Project id={id} />}</Route>
  <Route name="settings">{() => <Settings />}</Route>
  <Navigate to={toRoute({ name: 'home' })} />
</Switch>

Headless Router

import { createHeadlessRouter } from 'react-iten/headless'

const router = createHeadlessRouter<Routes>({
  initial: toRoute({ name: 'home' }),
})

router.store.getState()
await router.store.navigate({ target: toRoute({ name: 'settings' }) })

The store is scoped to the router instance and uses useSyncExternalStore for React subscriptions.

URL Sync

react-iten/url keeps URL support explicit and optional.

import { createUrlSync } from 'react-iten/url'

const sync = createUrlSync({
  router,
  parse: ({ url }) => parseRoute(url),
  format: ({ route }) => formatRoute(route),
})

await sync.hydrate()
sync.start()

Zod Runtime Validation

import { z } from 'zod'
import { createZodRoute, defineZodRoutes, zodNoParams } from 'react-iten/zod'

const schemas = defineZodRoutes({
  home: zodNoParams(),
  project: z.object({ id: z.string().min(1) }).strict(),
})

const toRoute = createZodRoute(schemas)

toRoute({ name: 'project', input: { id: 'alpha' } })

Entry Points

• react-iten: hooks, components, route utilities, and types
• react-iten/headless: hooks and scoped store without components
• react-iten/url: optional URL sync adapter
• react-iten/zod: optional Zod route factories and parsers
• react-iten/utils: route factories, guards, matching, and type utilities