Solid2

Navigation primitives

Import

import {
  useBeforeLeave,
  useHref,
  useInRouter,
  useIsRouting,
  useLinkState,
  useLocation,
  useMatch,
  useNavigate,
  useParams,
  usePreloadRoute,
  useResolvedPath,
  useRouteMatches,
  useSearchParams,
} from "@solidjs/router";

All primitives on this page except useInRouter throw when called outside a router. All of them throw when called with no reactive owner, such as from an event handler.

useInRouter

function useInRouter(): boolean;

Returns whether the calling component is rendered under a router.

const location = useInRouter() ? useLocation() : undefined;

useNavigate

function useNavigate(): Navigator;


interface Navigator {
  (to: string | TypedPath | number, options?: Partial<NavigateOptions>): void;
  (delta: number): void;
}
interface NavigateOptions<S = unknown> {
  resolve: boolean;
  replace: boolean;
  scroll: boolean;
  state: S;
}

Defaults are resolve: true, replace: false, and scroll: true.

const navigate = useNavigate();
navigate(Router.paths.users(42), { replace: true });
navigate(-1);

useLocation

function useLocation<S = unknown>(): Location<S>;
interface Location<S = unknown> {
  pathname: string;
  search: string;
  hash: string;
  query: SearchParams;
  state: Readonly<Partial<S>> | null;
  key: string;
}

Returns the reactive current location.

useParams

function useParams<T extends Params>(): T;
function useParams<P extends Params>(
  path: TypedPath<P>
): { [K in keyof P]: P[K] };

Returns the reactive merged parameters for the current route chain. The path argument is a type witness and is not matched at runtime.

Each value is decoded with decodeURIComponent after matching, so /item/%E7%8C%AB gives id: "猫". An encoded slash stays inside its parameter: /a%2Fb/view matched by /:name/view gives name: "a/b". A splat parameter is decoded segment by segment. A malformed escape is left as written.

useSearchParams

function useSearchParams<T extends SearchParams>(): [
  Partial<T>,
  (params: SetSearchParams, options?: Partial<NavigateOptions>) => void,
];


function useSearchParams<In, Out>(
  path: TypedSearchPath<In, Out>
): [Out, (params: Partial<In>, options?: Partial<NavigateOptions>) => void];

The no-argument form reads raw query values. The path-witness form runs synchronous search schemas from the current matched routes. The setter merges values and defaults to scroll: false and resolve: false.

useMatch

function useMatch<S extends string | TypedPath>(
  path: () => S,
  matchFilters?: MatchFilters
): () => PathMatch | undefined;

Matches the supplied path pattern against the current pathname. useMatch does not consult the route tree.

const match = useMatch(() => "/docs/*rest");
match()?.params.rest;

useRouteMatches

function useRouteMatches(): () => RouteMatch[];

Returns a copied root-to-leaf array of the resolved route-tree matches.

useIsRouting

function useIsRouting(): () => boolean;

Returns an accessor for pending programmatic navigation, native history traversal, and lazy route resolution.

usePreloadRoute

function usePreloadRoute(): (
  url: string | URL | TypedPath,
  options?: { preloadData?: boolean }
) => void;

Loads matched lazy components. Set preloadData: true to also run matched route preloads.

useLinkState

function useLinkState(
  href: () => string | TypedPath,
  options?: { end?: boolean }
): LinkState;
interface LinkState {
  active: () => boolean;
  current: () => boolean;
  pending: () => boolean;
}

active compares the path only and includes descendants unless end is true. current requires the same path and the same query, ignoring parameter order and the hash. pending matches the active in-flight target.

useResolvedPath

function useResolvedPath(path: () => string): () => string | undefined;

Resolves a path against the current route context.

useHref

function useHref<T extends string | undefined>(to: () => T): () => string | T;

Applies the history adapter's output rendering, such as the # prefix from hash history.

useBeforeLeave

function useBeforeLeave(listener: (event: BeforeLeaveEventArgs) => void): void;
interface BeforeLeaveEventArgs {
  from: Location;
  to: string | number;
  options?: Partial<NavigateOptions>;
  readonly defaultPrevented: boolean;
  preventDefault(): void;
  retry(force?: boolean): void;
}

Solid removes the listener when the owner is disposed. Call preventDefault() to block navigation. Call retry(true) to retry without running leave handlers again.

Related

Last updated: 10/15/26, 9:29 AMEdit this pageReport an issue with this page