Jarl

API Reference: jarl-react

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 asyncRouteAtom) 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

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

Renders an anchor (or element) linking to a route atom and param values. Clicking navigates by writing to the route atom instead of a full page load.

useLink offers the same behaviour to a link-like component of your own.

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).

useNavigate

const useNavigate: <T extends DefaultParams>(routeAtom: RouteAtom<T>) => (to: T, options?: NavOptions) => void

Returns a stable navigate function bound to one route atom. Calling it with param values pushes a new location; pass { replace: true } as a second argument for a replace navigation, mirroring the route atom's own setter (set(routeAtom, values, { replace: true })).

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.

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.

useNavigationGuard

const useNavigationGuard: (guard: NavigationGuardAtom) => void

Enforces a navigation guard atom for as long as the calling component is mounted - the React binding for enforceNavigationGuards, which documents what a guard can and cannot veto. Call it once per guard, wherever the state that guard reads is owned.

The guard atom must be stable across renders - defined at module scope, or memoised - since a new one on every render re-registers on every render.

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;
};

Options for useLink/Link: 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: the resolved href, whether the link is currently active, and a click handler that performs the navigation.

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;
};

Props for Route: which route atom to render on, its children, and how strictly it must match.

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;
};

Props for Switch: its <Route> children, in precedence order, and a fallback for when none match.