jarl-react API reference

The core exports of jarl-react - the React bindings (components + hooks) built on top of the framework-agnostic route atoms in jarl-atoms. jarl-react does not re-export jarl-atoms: get your route atoms from jarl-atoms and these components/hooks from jarl-react. See the v1 History page for how JARL's original RoutingProvider/routing() HOC API worked, and why the atomic model replaced it.

Every hook here takes a route atom as its first argument. jarl-react also re-exports jotai's own useAtom, useAtomValue and useSetAtom, so composing directly with a route atom (or with jarl-atoms primitives like resolvedAtom) never needs a separate direct dependency on jotai.

The reference below is generated from the doc comments on each export. Components list only their own props: Link also forwards any other standard anchor prop (className, target, ...) straight through to the rendered element.

Components

Link

const Link: <T extends DefaultParams>(props: LinkProps<T>) => Element

Renders an anchor (or element) linking to a route atom + param values. Clicking navigates by writing to the route atom instead of a full page load. Hooks-first: Link is a thin wrapper over useLink, so anything Link can do is also available directly via the hook.

prop	type	required	description
route	RouteAtom<T>	yes	The route atom this link points at.
to	T | undefined	no	Param values to reverse into a path for this route.
activeClassName	string | undefined	no	Extra class name applied only while this link is active.
element	ElementType | undefined	no	Element (or component) to render as. Ignored when children is a function.
children	ReactNode | ((props: LinkChildrenRenderProps) => ReactNode)	no	Standard React children, or a render-prop function receiving { href, active, onClick } for full control over rendering. Prefer useLink directly for markup that isn't anchor-shaped.
exact	boolean | undefined	no	Only report active for an exact match, rather than any ancestor route too.

Route

const Route: <T extends DefaultParams>(props: RouteProps<T>) => Element | null

Renders its children only while on matches the current location. children can be plain nodes, or a function receiving the matched route's param values for cases that need them.

Wrap several of these in a Switch to render only the first that matches, with a catch-all for when none does.

prop	type	required	description
on	RouteAtom<T>	yes	The route atom to render on.
children	ReactNode | ((values: T) => ReactNode | undefined)	no	Plain nodes, or a function receiving the matched route's param values.
exact	boolean | undefined	no	Only render when this is an exact (leaf) match, not just an ancestor match.

Switch

const Switch: (props: SwitchProps) => Element

Renders only the first of its <Route> children that is currently active, or fallback when none of them is.

Children must be <Route> elements; conditional children ({flag && <Route ... />}) are fine, but a fragment or wrapper around a group of routes hides them and throws.

prop	type	required	description
children	ReactNode	no	<Route> elements, in precedence order.
fallback	ReactNode	no	Rendered when no child route is active - a catch-all for this level.

Hooks

useRoute

const useRoute: <T extends DefaultParams>(routeAtom: RouteAtom<T>) => RouteReturn<T>

Subscribes to a route atom and returns its current match state (match, exact, values, reverse, ...). Equivalent to useAtomValue(routeAtom), given a name that reads naturally at call sites and mirrors useRoute conventions in other routers.

useNavigate

const useNavigate: <T extends DefaultParams>(routeAtom: RouteAtom<T>) => (to: T) => void

Returns a stable navigate function bound to one route atom. Calling it with param values pushes a new location.

useIsActive

const useIsActive: <T extends DefaultParams>(routeAtom: RouteAtom<T>, { exact }?: { exact?: boolean; }) => boolean

Returns whether a route atom currently matches - optionally requiring an exact (leaf) match, rather than matching because a descendant route is active too.

useHref

const useHref: <T extends DefaultParams>(routeAtom: RouteAtom<T>, to: T) => string

Reverses a route atom's pattern with the given param values into a URL path. Still subscribes to the route atom, since reverse depends on ancestor state, so it re-renders on navigation even when the returned href doesn't change.

useLink

const useLink: <T extends DefaultParams>(routeAtom: RouteAtom<T>, to: T, { exact }?: UseLinkOptions) => UseLinkResult

The hook Link is built on top of. Combines href, active state and a navigation handler for a route atom + param values, so link-like components can be built without needing the Link component itself.

Types

UseLinkResult

export type UseLinkResult = {
  href: string;
  active: boolean;
  /** Attach directly to a native element's onClick, or call with no args. */
  onClick: (event?: { preventDefault?: () => void }) => void;
};

Everything a link-like component needs: where it points, whether it's active, and how to follow it.

UseLinkOptions

export type UseLinkOptions = {
  /** Only report `active` for an exact match, rather than any ancestor route too. */
  exact?: boolean;
};

How strictly a link reports itself active.

LinkChildrenRenderProps

export type LinkChildrenRenderProps = {
  href: string;
  active: boolean;
  onClick: () => void;
};

What Link's function-as-child form receives.

LinkProps

export type LinkProps<T extends DefaultParams> = {
  /** The route atom this link points at. */
  route: RouteAtom<T>;
  /** Param values to reverse into a path for this route. */
  to?: T;
  /** Extra class name applied only while this link is active. */
  activeClassName?: string;
  /** Element (or component) to render as. Ignored when `children` is a function. */
  element?: ElementType;
  /**
   * Standard React children, or a render-prop function receiving `{ href, active, onClick }` for
   * full control over rendering. Prefer `useLink` directly for markup that isn't anchor-shaped.
   */
  children?: ReactNode | ((props: LinkChildrenRenderProps) => ReactNode);
} & UseLinkOptions &
  Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children" | "href" | "onClick">;

Link's own props, plus any standard anchor attribute, which is forwarded to the rendered element.

RouteProps

export type RouteProps<T extends DefaultParams> = {
  /** The route atom to render on. */
  on: RouteAtom<T>;
  /** Plain nodes, or a function receiving the matched route's param values. */
  children?: ReactNode | ((values: T) => ReactNode | undefined);
  /** Only render when this is an exact (leaf) match, not just an ancestor match. */
  exact?: boolean;
};

SwitchProps

export type SwitchProps = {
  /** `<Route>` elements, in precedence order. */
  children?: ReactNode;
  /** Rendered when no child route is active - a catch-all for this level. */
  fallback?: ReactNode;
};