react-router

react-router

Version 7.13.1
Published 23 hours ago
4.18 MB
2 dependencies
MIT license

Install

npm i react-router

yarn add react-router

pnpm add react-router

Overview

Declarative routing for React

Index

Variables

variable createRequestHandler

const createRequestHandler: CreateRequestHandlerFunction;

variable createRoutesFromElements

const createRoutesFromElements: (
    children: React.ReactNode,
    parentPath?: number[]
) => RouteObject[];

Create route objects from JSX elements instead of arrays of objects.
Parameter children
The React children to convert into a route config
Parameter parentPath
The path of the parent route, used to generate unique IDs. This is used for internal recursion and is not intended to be used by the application developer.
Returns
An array of RouteObjects that can be used with a DataRouter
Example 1
const routes = createRoutesFromElements( <> <Route index loader={step1Loader} Component={StepOne} /> <Route path="step-2" loader={step2Loader} Component={StepTwo} /> <Route path="step-3" loader={step3Loader} Component={StepThree} /> </> );
const router = createBrowserRouter(routes);
function App() { return <RouterProvider router={router} />; }
createRoutesFromElements
Utils data
Modifiers
- @public

variable createSession

const createSession: CreateSessionFunction;

Creates a new Session object.
Note: This function is typically not invoked directly by application code. Instead, use a SessionStorage object's getSession method.

variable Form

const Form: React.ForwardRefExoticComponent<any>;

A progressively enhanced HTML [<form>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) that submits data to actions via [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch), activating pending states in useNavigation which enables advanced user interfaces beyond a basic HTML [<form>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form). After a form's action completes, all data on the page is automatically revalidated to keep the UI in sync with the data.
Because it uses the HTML form API, server rendered pages are interactive at a basic level before JavaScript loads. Instead of React Router managing the submission, the browser manages the submission as well as the pending states (like the spinning favicon). After JavaScript loads, React Router takes over enabling web application user experiences.
Form is most useful for submissions that should also change the URL or otherwise add an entry to the browser history stack. For forms that shouldn't manipulate the browser [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack, use `<fetcher.Form>`.
Parameter action
n/a
Parameter discover
n/a
Parameter encType
n/a
Parameter fetcherKey
n/a
Parameter method
n/a
Parameter navigate
n/a
Parameter onSubmit
n/a
Parameter preventScrollReset
n/a
Parameter relative
n/a
Parameter reloadDocument
n/a
Parameter replace
n/a
Parameter state
n/a
Parameter viewTransition
n/a
Parameter unstable_defaultShouldRevalidate
n/a
Returns
A progressively enhanced [<form>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) component
Example 1
import { Form } from "react-router";
function NewEvent() { return ( ); }
Components framework data
Modifiers
- @public

variable IDLE_BLOCKER

const IDLE_BLOCKER: BlockerUnblocked;

variable IDLE_FETCHER

const IDLE_FETCHER: {
    state: 'idle';
    formMethod: undefined;
    formAction: undefined;
    formEncType: undefined;
    text: undefined;
    formData: undefined;
    json: undefined;
    data: any;
};

variable IDLE_NAVIGATION

const IDLE_NAVIGATION: {
    state: 'idle';
    location: undefined;
    formMethod: undefined;
    formAction: undefined;
    formEncType: undefined;
    formData: undefined;
    json: undefined;
    text: undefined;
};

variable isCookie

const isCookie: IsCookieFunction;

Returns true if an object is a Remix cookie container.
See Also
- https://remix.run/utils/cookies#iscookie

variable isSession

const isSession: IsSessionFunction;

Returns true if an object is a React Router session.
See Also
- https://reactrouter.com/api/utils/isSession

variable Link

const Link: React.ForwardRefExoticComponent<any>;

A progressively enhanced [<a href>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) wrapper to enable navigation with client-side routing.
Parameter
{LinkProps.discover} props.discover [modes: framework] n/a
Parameter
{LinkProps.prefetch} props.prefetch [modes: framework] n/a
Parameter
{LinkProps.preventScrollReset} props.preventScrollReset [modes: framework, data] n/a
Parameter
{LinkProps.relative} props.relative n/a
Parameter
{LinkProps.reloadDocument} props.reloadDocument n/a
Parameter
{LinkProps.replace} props.replace n/a
Parameter
{LinkProps.state} props.state n/a
Parameter
{LinkProps.to} props.to n/a
Parameter
{LinkProps.viewTransition} props.viewTransition [modes: framework, data] n/a
Parameter
{LinkProps.unstable_defaultShouldRevalidate} props.unstable_defaultShouldRevalidate n/a
Parameter
{LinkProps.unstable_mask} props.unstable_mask [modes: framework, data] n/a
Example 1
import { Link } from "react-router";
Dashboard;
<Link to={{ pathname: "/some/path", search: "?query=string", hash: "#hash", }} />;
Components
Modifiers
- @public

variable NavLink

const NavLink: React.ForwardRefExoticComponent<any>;

Wraps `<Link>` with additional props for styling active and pending states.
- Automatically applies classes to the link based on its active and pending states, see NavLinkProps.className - Note that pending is only available with Framework and Data modes. - Automatically applies aria-current="page" to the link when the link is active. See [aria-current](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) on MDN. - States are additionally available through the className, style, and children render props. See NavLinkRenderProps.
Parameter
{NavLinkProps.caseSensitive} props.caseSensitive n/a
Parameter
{NavLinkProps.children} props.children n/a
Parameter
{NavLinkProps.className} props.className n/a
Parameter
{NavLinkProps.discover} props.discover [modes: framework] n/a
Parameter
{NavLinkProps.end} props.end n/a
Parameter
{NavLinkProps.prefetch} props.prefetch [modes: framework] n/a
Parameter
{NavLinkProps.preventScrollReset} props.preventScrollReset [modes: framework, data] n/a
Parameter
{NavLinkProps.relative} props.relative n/a
Parameter
{NavLinkProps.reloadDocument} props.reloadDocument n/a
Parameter
{NavLinkProps.replace} props.replace n/a
Parameter
{NavLinkProps.state} props.state n/a
Parameter
{NavLinkProps.style} props.style n/a
Parameter
{NavLinkProps.to} props.to n/a
Parameter
{NavLinkProps.viewTransition} props.viewTransition [modes: framework, data] n/a
Example 1
Messages
// Using render props <NavLink to="/messages" className={({ isActive, isPending }) => isPending ? "pending" : isActive ? "active" : "" } > Messages
Components
Modifiers
- @public

variable redirect

const redirect: RedirectFunction;

A redirect [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). Sets the status code and the [Location](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location) header. Defaults to [302 Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
Parameter url
The URL to redirect to.
Parameter init
The status code or a ResponseInit object to be included in the response.
Returns
A [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the redirect status and [Location](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location) header.
Example 1
import { redirect } from "react-router";
export async function loader({ request }: Route.LoaderArgs) { if (!isLoggedIn(request)) throw redirect("/login"); }
// ... }
Utils framework data
Modifiers
- @public

variable redirectDocument

const redirectDocument: RedirectFunction;

A redirect [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) that will force a document reload to the new location. Sets the status code and the [Location](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location) header. Defaults to [302 Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
import { redirectDocument } from "react-router"; import { destroySession } from "../sessions.server"; export async function action({ request }: Route.ActionArgs) { let session = await getSession(request.headers.get("Cookie")); return redirectDocument("/", { headers: { "Set-Cookie": await destroySession(session) } }); }
Utils framework data
Parameter url
The URL to redirect to.
Parameter init
The status code or a ResponseInit object to be included in the response.
Returns
A [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the redirect status and [Location](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location) header.
Modifiers
- @public

variable replace

const replace: RedirectFunction;

A redirect [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) that will perform a [history.replaceState](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState) instead of a [history.pushState](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) for client-side navigation redirects. Sets the status code and the [Location](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location) header. Defaults to [302 Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
Parameter url
The URL to redirect to.
Parameter init
The status code or a ResponseInit object to be included in the response.
Returns
A [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the redirect status and [Location](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location) header.
Example 1
import { replace } from "react-router";
export async function loader() { return replace("/new-location"); }
Utils framework data
Modifiers
- @public

variable UNSAFE_DataRouterContext

const UNSAFE_DataRouterContext: React.Context<DataRouterContextObject>;

variable UNSAFE_DataRouterStateContext

const UNSAFE_DataRouterStateContext: React.Context<RouterState>;

variable UNSAFE_FetchersContext

const UNSAFE_FetchersContext: React.Context<FetchersContextObject>;

variable UNSAFE_FrameworkContext

const UNSAFE_FrameworkContext: React.Context<FrameworkContextObject>;

variable UNSAFE_hydrationRouteProperties

const UNSAFE_hydrationRouteProperties: (
    | 'caseSensitive'
    | 'path'
    | 'id'
    | 'middleware'
    | 'loader'
    | 'action'
    | 'hasErrorBoundary'
    | 'shouldRevalidate'
    | 'handle'
    | 'index'
    | 'children'
    | 'element'
    | 'hydrateFallbackElement'
    | 'errorElement'
    | 'Component'
    | 'HydrateFallback'
    | 'ErrorBoundary'
    | 'lazy'
)[];

variable UNSAFE_LocationContext

const UNSAFE_LocationContext: React.Context<LocationContextObject>;

variable UNSAFE_NavigationContext

const UNSAFE_NavigationContext: React.Context<NavigationContextObject>;

variable UNSAFE_RouteContext

const UNSAFE_RouteContext: React.Context<RouteContextObject>;

variable UNSAFE_SingleFetchRedirectSymbol

const UNSAFE_SingleFetchRedirectSymbol: Symbol;

variable UNSAFE_ViewTransitionContext

const UNSAFE_ViewTransitionContext: React.Context<ViewTransitionContextObject>;

variable unstable_matchRSCServerRequest

const unstable_matchRSCServerRequest: ({
    allowedActionOrigins,
    createTemporaryReferenceSet,
    basename,
    decodeReply,
    requestContext,
    loadServerAction,
    decodeAction,
    decodeFormState,
    onError,
    request,
    routes,
    generateResponse,
}: {
    allowedActionOrigins?: string[];
    createTemporaryReferenceSet: () => unknown;
    basename?: string;
    decodeReply?: DecodeReplyFunction;
    decodeAction?: DecodeActionFunction;
    decodeFormState?: DecodeFormStateFunction;
    requestContext?: RouterContextProvider;
    loadServerAction?: LoadServerActionFunction;
    onError?: (error: unknown) => void;
    request: Request;
    routes: RSCRouteConfigEntry[];
    generateResponse: (
        match: RSCMatch,
        {
            onError,
            temporaryReferences,
        }: { onError(error: unknown): string; temporaryReferences: unknown }
    ) => Response;
}) => Promise<Response>;

Functions

function Await

Await: <Resolve>({
    children,
    errorElement,
    resolve,
}: AwaitProps<Resolve>) => React.JSX.Element;

Used to render promise values with automatic error handling.
**Note:** <Await> expects to be rendered inside a [<React.Suspense>](https://react.dev/reference/react/Suspense)
Parameter props
Props
Parameter
{AwaitProps.children} props.children n/a
Parameter
{AwaitProps.errorElement} props.errorElement n/a
Parameter
{AwaitProps.resolve} props.resolve n/a
Returns
React element for the rendered awaited value
Example 1
import { Await, useLoaderData } from "react-router";
export async function loader() { // not awaited const reviews = getReviews(); // awaited (blocks the transition) const book = await fetch("/api/book").then((res) => res.json()); return { book, reviews }; }
function Book() { const { book, reviews } = useLoaderData(); return ( {book.title} {book.description} <React.Suspense fallback={}> <Await resolve={reviews} errorElement={ Could not load reviews 😬 } children={(resolvedReviews) => ( <Reviews items={resolvedReviews} /> )} /> </React.Suspense> ); }
Components framework data
Modifiers
- @public

function BrowserRouter

BrowserRouter: ({
    basename,
    children,
    unstable_useTransitions,
    window,
}: BrowserRouterProps) => React.JSX.Element;

A declarative `<Router>` using the browser [History](https://developer.mozilla.org/en-US/docs/Web/API/History) API for client-side routing.
Declarative Routers declarative
Parameter props
Props
Parameter
{BrowserRouterProps.basename} props.basename n/a
Parameter
{BrowserRouterProps.children} props.children n/a
Parameter
{BrowserRouterProps.unstable_useTransitions} props.unstable_useTransitions n/a
Parameter
{BrowserRouterProps.window} props.window n/a
Returns
A declarative `<Router>` using the browser [History](https://developer.mozilla.org/en-US/docs/Web/API/History) API for client-side routing.
Modifiers
- @public

function createBrowserRouter

createBrowserRouter: (routes: RouteObject[], opts?: DOMRouterOpts) => Router;

Create a new data router that manages the application path via [history.pushState](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) and [history.replaceState](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState).
Data Routers data
Parameter routes
Application routes
Parameter opts
Options
Parameter
{DOMRouterOpts.basename} opts.basename n/a
Parameter
{DOMRouterOpts.dataStrategy} opts.dataStrategy n/a
Parameter
{DOMRouterOpts.future} opts.future n/a
Parameter
{DOMRouterOpts.getContext} opts.getContext n/a
Parameter
{DOMRouterOpts.hydrationData} opts.hydrationData n/a
Parameter
{DOMRouterOpts.unstable_instrumentations} opts.unstable_instrumentations n/a
Parameter
{DOMRouterOpts.patchRoutesOnNavigation} opts.patchRoutesOnNavigation n/a
Parameter
{DOMRouterOpts.window} opts.window n/a
Returns
An initialized data router to pass to `<RouterProvider>`
Modifiers
- @public

function createContext

createContext: <T>(defaultValue?: T) => RouterContext<T>;

Creates a type-safe RouterContext object that can be used to store and retrieve arbitrary values in [action](../../start/framework/route-module#action)s, [loader](../../start/framework/route-module#loader)s, and [middleware](../../how-to/middleware). Similar to React's [createContext](https://react.dev/reference/react/createContext), but specifically designed for React Router's request/response lifecycle.
If a defaultValue is provided, it will be returned from context.get() when no value has been set for the context. Otherwise, reading this context when no value has been set will throw an error.
import { createContext } from "react-router"; // Create a context for user data export const userContext = createContext<User | null>(null);
import { getUserFromSession } from "~/auth.server"; import { userContext } from "~/context"; export const authMiddleware = async ({ context, request, }) => { const user = await getUserFromSession(request); context.set(userContext, user); };
import { userContext } from "~/context"; export async function loader({ context, }: Route.LoaderArgs) { const user = context.get(userContext); if (!user) { throw new Response("Unauthorized", { status: 401 }); } return { user }; }
Utils framework data
Parameter defaultValue
An optional default value for the context. This value will be returned if no value has been set for this context.
Returns
A RouterContext object that can be used with context.get() and context.set() in [action](../../start/framework/route-module#action)s, [loader](../../start/framework/route-module#loader)s, and [middleware](../../how-to/middleware).
Modifiers
- @public

function createCookie

createCookie: (name: string, cookieOptions?: CookieOptions) => Cookie;

Creates a logical container for managing a browser cookie from the server.

function createCookieSessionStorage

createCookieSessionStorage: <Data = SessionData, FlashData = Data>({
    cookie: cookieArg,
}?: CookieSessionStorageOptions) => SessionStorage<Data, FlashData>;

Creates and returns a SessionStorage object that stores all session data directly in the session cookie itself.
This has the advantage that no database or other backend services are needed, and can help to simplify some load-balanced scenarios. However, it also has the limitation that serialized session data may not exceed the browser's maximum cookie size. Trade-offs!

function createHashRouter

createHashRouter: (routes: RouteObject[], opts?: DOMRouterOpts) => Router;

Create a new data router that manages the application path via the URL [hash](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash).
Data Routers data
Parameter routes
Application routes
Parameter opts
Options
Parameter
{DOMRouterOpts.basename} opts.basename n/a
Parameter
{DOMRouterOpts.future} opts.future n/a
Parameter
{DOMRouterOpts.getContext} opts.getContext n/a
Parameter
{DOMRouterOpts.hydrationData} opts.hydrationData n/a
Parameter
{DOMRouterOpts.unstable_instrumentations} opts.unstable_instrumentations n/a
Parameter
{DOMRouterOpts.dataStrategy} opts.dataStrategy n/a
Parameter
{DOMRouterOpts.patchRoutesOnNavigation} opts.patchRoutesOnNavigation n/a
Parameter
{DOMRouterOpts.window} opts.window n/a
Returns
An initialized data router to pass to `<RouterProvider>`
Modifiers
- @public

function createMemoryRouter

createMemoryRouter: (routes: RouteObject[], opts?: MemoryRouterOpts) => Router$1;

Create a new DataRouter that manages the application path using an in-memory [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack. Useful for non-browser environments without a DOM API.
Data Routers data
Parameter routes
Application routes
Parameter opts
Options
Parameter
{MemoryRouterOpts.basename} opts.basename n/a
Parameter
{MemoryRouterOpts.dataStrategy} opts.dataStrategy n/a
Parameter
{MemoryRouterOpts.future} opts.future n/a
Parameter
{MemoryRouterOpts.getContext} opts.getContext n/a
Parameter
{MemoryRouterOpts.hydrationData} opts.hydrationData n/a
Parameter
{MemoryRouterOpts.initialEntries} opts.initialEntries n/a
Parameter
{MemoryRouterOpts.initialIndex} opts.initialIndex n/a
Parameter
{MemoryRouterOpts.unstable_instrumentations} opts.unstable_instrumentations n/a
Parameter
{MemoryRouterOpts.patchRoutesOnNavigation} opts.patchRoutesOnNavigation n/a
Returns
An initialized DataRouter to pass to `<RouterProvider>`
Modifiers
- @public

function createMemorySessionStorage

createMemorySessionStorage: <Data = SessionData, FlashData = Data>({
    cookie,
}?: MemorySessionStorageOptions) => SessionStorage<Data, FlashData>;

Creates and returns a simple in-memory SessionStorage object, mostly useful for testing and as a reference implementation.
Note: This storage does not scale beyond a single process, so it is not suitable for most production scenarios.

function createPath

createPath: ({ pathname, search, hash }: Partial<Path>) => string;

Creates a string URL path from the given pathname, search, and hash components.
Utils

function createRoutesFromChildren

createRoutesFromChildren: (
    children: React.ReactNode,
    parentPath?: number[]
) => RouteObject[];

Creates a route config from a React "children" object, which is usually either a <Route> element or an array of them. Used internally by <Routes> to create a route config from its children.
Utils data
Parameter children
The React children to convert into a route config
Parameter parentPath
The path of the parent route, used to generate unique IDs.
Returns
An array of RouteObjects that can be used with a DataRouter

function createSearchParams

createSearchParams: (init?: URLSearchParamsInit) => URLSearchParams;

Creates a URLSearchParams object using the given initializer.
This is identical to new URLSearchParams(init) except it also supports arrays as values in the object form of the initializer instead of just strings. This is convenient when you need multiple values for a given key, but don't want to use an array initializer.
For example, instead of:
```tsx let searchParams = new URLSearchParams([ ['sort', 'name'], ['sort', 'price'] ]); ``` you can do:
``` let searchParams = createSearchParams({ sort: ['name', 'price'] }); ```
Utils

function createSessionStorage

createSessionStorage: <Data = SessionData, FlashData = Data>({
    cookie: cookieArg,
    createData,
    readData,
    updateData,
    deleteData,
}: SessionIdStorageStrategy<Data, FlashData>) => SessionStorage<Data, FlashData>;

Creates a SessionStorage object using a SessionIdStorageStrategy.
Note: This is a low-level API that should only be used if none of the existing session storage options meet your requirements.

function createStaticHandler

createStaticHandler: (
    routes: RouteObject[],
    opts?: CreateStaticHandlerOptions
) => StaticHandler;

Create a static handler to perform server-side data loading
Parameter routes
The route objects to create a static handler for
Parameter opts
Options
Parameter
opts.basename The base URL for the static handler (default: /)
Parameter
opts.future Future flags for the static handler
Returns
A static handler that can be used to query data for the provided routes
Example 1
export async function handleRequest(request: Request) { let { query, dataRoutes } = createStaticHandler(routes); let context = await query(request);
if (context instanceof Response) { return context; }
let router = createStaticRouter(dataRoutes, context); return new Response( ReactDOMServer.renderToString(<StaticRouterProvider ... />), { headers: { "Content-Type": "text/html" } } ); }
Data Routers data
Modifiers
- @public

function createStaticRouter

createStaticRouter: (
    routes: RouteObject[],
    context: StaticHandlerContext,
    opts?: { future?: Partial<FutureConfig$1> }
) => Router;

Create a static DataRouter for server-side rendering
Parameter routes
The route objects to create a static DataRouter for
Parameter context
The StaticHandlerContext returned from StaticHandler's query
Parameter opts
Options
Parameter
opts.future Future flags for the static DataRouter
Returns
A static DataRouter that can be used to render the provided routes
Example 1
export async function handleRequest(request: Request) { let { query, dataRoutes } = createStaticHandler(routes); let context = await query(request);
if (context instanceof Response) { return context; }
let router = createStaticRouter(dataRoutes, context); return new Response( ReactDOMServer.renderToString(<StaticRouterProvider ... />), { headers: { "Content-Type": "text/html" } } ); }
Data Routers data
Modifiers
- @public

function data

data: <D>(data: D, init?: number | ResponseInit) => DataWithResponseInit<D>;

Create "responses" that contain headers/status without forcing serialization into an actual [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)
Parameter data
The data to be included in the response.
Parameter init
The status code or a ResponseInit object to be included in the response.
Returns
A DataWithResponseInit instance containing the data and response init.
Example 1
import { data } from "react-router";
export async function action({ request }: Route.ActionArgs) { let formData = await request.formData(); let item = await createItem(formData); return data(item, { headers: { "X-Custom-Header": "value" } status: 201, }); }
Utils framework data
Modifiers
- @public

function generatePath

generatePath: <Path extends string>(
    originalPath: Path,
    params?: { [key in PathParam<Path>]: string }
) => string;

Returns a path with params interpolated.
Parameter originalPath
The original path to generate.
Parameter params
The parameters to interpolate into the path.
Returns
The generated path with parameters interpolated.
Example 1
import { generatePath } from "react-router";
generatePath("/users/:id", { id: "123" }); // "/users/123"
Utils
Modifiers
- @public

function HashRouter

HashRouter: ({
    basename,
    children,
    unstable_useTransitions,
    window,
}: HashRouterProps) => React.JSX.Element;

A declarative `<Router>` that stores the location in the [hash](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash) portion of the URL so it is not sent to the server.
Declarative Routers declarative
Parameter props
Props
Parameter
{HashRouterProps.basename} props.basename n/a
Parameter
{HashRouterProps.children} props.children n/a
Parameter
{HashRouterProps.unstable_useTransitions} props.unstable_useTransitions n/a
Parameter
{HashRouterProps.window} props.window n/a
Returns
A declarative `<Router>` using the URL [hash](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash) for client-side routing.
Modifiers
- @public

function href

href: <Path extends string>(path: Path, ...args: Args[Path]) => string;

Returns a resolved URL path for the specified route.
```tsx const h = href("/:lang?/about", { lang: "en" }) // -> /en/about
<Link to={href("/products/:id", { id: "abc123" })} /> ```

function isRouteErrorResponse

isRouteErrorResponse: (error: any) => error is ErrorResponse;

Check if the given error is an ErrorResponse generated from a 4xx/5xx [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) thrown from an [action](../../start/framework/route-module#action) or [loader](../../start/framework/route-module#loader) function.
Parameter error
The error to check.
Returns
true if the error is an ErrorResponse, false otherwise.
Example 1
import { isRouteErrorResponse } from "react-router";
export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) { if (isRouteErrorResponse(error)) { return ( <> Error: ${error.status}: ${error.statusText} {error.data} </> ); }
return ( Error: {error instanceof Error ? error.message : "Unknown Error"} ); }
Utils framework data
Modifiers
- @public

function Links

Links: ({ nonce, crossOrigin }: LinksProps) => React.JSX.Element;

Renders all the [<link>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) tags created by the route module's [links](../../start/framework/route-module#links) export. You should render it inside the [<head>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) of your document.
Parameter props
Props
Parameter
{LinksProps.nonce} props.nonce n/a
Parameter
{LinksProps.crossOrigin} props.crossOrigin n/a
Returns
A collection of React elements for [<link>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) tags
Example 1
import { Links } from "react-router";
export default function Root() { return ( ); }
Components framework
Modifiers
- @public

function matchPath

matchPath: <ParamKey extends ParamParseKey<Path>, Path extends string>(
    pattern: PathPattern<Path> | Path,
    pathname: string
) => PathMatch<ParamKey> | null;

Performs pattern matching on a URL pathname and returns information about the match.
Utils
Parameter pattern
The pattern to match against the URL pathname. This can be a string or a PathPattern object. If a string is provided, it will be treated as a pattern with caseSensitive set to false and end set to true.
Parameter pathname
The URL pathname to match against the pattern.
Returns
A path match object if the pattern matches the pathname, or null if it does not match.
Modifiers
- @public

function matchRoutes

matchRoutes: <RouteObjectType extends AgnosticRouteObject = AgnosticRouteObject>(
    routes: RouteObjectType[],
    locationArg: Partial<Location> | string,
    basename?: string
) => AgnosticRouteMatch<string, RouteObjectType>[] | null;

Matches the given routes to a location and returns the match data.
Parameter routes
The array of route objects to match against.
Parameter locationArg
The location to match against, either a string path or a partial Location object
Parameter basename
Optional base path to strip from the location before matching. Defaults to /.
Returns
An array of matched routes, or null if no matches were found.
Example 1
import { matchRoutes } from "react-router";
let routes = [{ path: "/", Component: Root, children: [{ path: "dashboard", Component: Dashboard, }] }];
matchRoutes(routes, "/dashboard"); // [rootMatch, dashboardMatch]
Utils
Modifiers
- @public

function MemoryRouter

MemoryRouter: ({
    basename,
    children,
    initialEntries,
    initialIndex,
    unstable_useTransitions,
}: MemoryRouterProps) => React.ReactElement;

A declarative `<Router>` that stores all entries in memory.
Declarative Routers declarative
Parameter props
Props
Parameter
{MemoryRouterProps.basename} props.basename n/a
Parameter
{MemoryRouterProps.children} props.children n/a
Parameter
{MemoryRouterProps.initialEntries} props.initialEntries n/a
Parameter
{MemoryRouterProps.initialIndex} props.initialIndex n/a
Parameter
{MemoryRouterProps.unstable_useTransitions} props.unstable_useTransitions n/a
Returns
A declarative in-memory `<Router>` for client-side routing.
Modifiers
- @public

function Meta

Meta: () => React.JSX.Element;

Renders all the [<meta>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) tags created by the route module's [meta](../../start/framework/route-module#meta) export. You should render it inside the [<head>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) of your document.
Returns
A collection of React elements for [<meta>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) tags
Example 1
import { Meta } from "react-router";
export default function Root() { return ( ); }
Components framework
Modifiers
- @public

function Navigate

Navigate: ({ to, replace, state, relative }: NavigateProps) => null;

A component-based version of useNavigate to use in a [React.Component class](https://react.dev/reference/react/Component) where hooks cannot be used.
It's recommended to avoid using this component in favor of useNavigate.
Parameter props
Props
Parameter
{NavigateProps.relative} props.relative n/a
Parameter
{NavigateProps.replace} props.replace n/a
Parameter
{NavigateProps.state} props.state n/a
Parameter
{NavigateProps.to} props.to n/a
Returns
{void}
Example 1
Components
Modifiers
- @public

function Outlet

Outlet: (props: OutletProps) => React.ReactElement | null;

Renders the matching child route of a parent route or nothing if no child route matches.
Parameter props
Props
Parameter
{OutletProps.context} props.context n/a
Returns
React element for the rendered outlet or null if no child route matches.
Example 1
import { Outlet } from "react-router";
export default function SomeParent() { return ( Parent Content ); }
Components
Modifiers
- @public

function parsePath

parsePath: (path: string) => Partial<Path>;

Parses a string URL path into its separate pathname, search, and hash components.
Utils

function PrefetchPageLinks

PrefetchPageLinks: ({
    page,
    ...linkProps
}: PageLinkDescriptor) => React.JSX.Element | null;

Renders [<link rel=prefetch|modulepreload>](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/rel) tags for modules and data of another page to enable an instant navigation to that page. [<Link prefetch>](./Link#prefetch) uses this internally, but you can render it to prefetch a page for any other reason.
For example, you may render one of this as the user types into a search field to prefetch search results before they click through to their selection.
Parameter props
Props
Parameter
{PageLinkDescriptor.page} props.page n/a
Parameter
props.linkProps Additional props to spread onto the [<link>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) tags, such as [crossOrigin](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/crossOrigin), [integrity](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/integrity), [rel](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/rel), etc.
Returns
A collection of React elements for [<link>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) tags
Example 1
import { PrefetchPageLinks } from "react-router";
Components framework
Modifiers
- @public

function renderMatches

renderMatches: (matches: RouteMatch[] | null) => React.ReactElement | null;

Renders the result of matchRoutes into a React element.
Utils
Parameter matches
The array of route matches to render
Returns
A React element that renders the matched routes or null if no matches
Modifiers
- @public

function resolvePath

resolvePath: (to: To, fromPathname?: string) => Path;

Returns a resolved Path object relative to the given pathname.
Utils
Parameter to
The path to resolve, either a string or a partial Path object.
Parameter fromPathname
The pathname to resolve the path from. Defaults to /.
Returns
A Path object with the resolved pathname, search, and hash.
Modifiers
- @public

function Route

Route: (props: RouteProps) => React.ReactElement | null;

Configures an element to render when a pattern matches the current location. It must be rendered within a Routes element. Note that these routes do not participate in data loading, actions, code splitting, or any other route module features.
Parameter props
Props
Parameter
{PathRouteProps.action} props.action n/a
Parameter
{PathRouteProps.caseSensitive} props.caseSensitive n/a
Parameter
{PathRouteProps.Component} props.Component n/a
Parameter
{PathRouteProps.children} props.children n/a
Parameter
{PathRouteProps.element} props.element n/a
Parameter
{PathRouteProps.ErrorBoundary} props.ErrorBoundary n/a
Parameter
{PathRouteProps.errorElement} props.errorElement n/a
Parameter
{PathRouteProps.handle} props.handle n/a
Parameter
{PathRouteProps.HydrateFallback} props.HydrateFallback n/a
Parameter
{PathRouteProps.hydrateFallbackElement} props.hydrateFallbackElement n/a
Parameter
{PathRouteProps.id} props.id n/a
Parameter
{PathRouteProps.index} props.index n/a
Parameter
{PathRouteProps.lazy} props.lazy n/a
Parameter
{PathRouteProps.loader} props.loader n/a
Parameter
{PathRouteProps.path} props.path n/a
Parameter
{PathRouteProps.shouldRevalidate} props.shouldRevalidate n/a
Returns
{void}
Example 1
// Usually used in a declarative router function App() { return ( <Route index element={} /> <Route path="step-2" element={} /> <Route path="step-3" element={} /> ); }
// But can be used with a data router as well if you prefer the JSX notation const routes = createRoutesFromElements( <> <Route index loader={step1Loader} Component={StepOne} /> <Route path="step-2" loader={step2Loader} Component={StepTwo} /> <Route path="step-3" loader={step3Loader} Component={StepThree} /> </> );
const router = createBrowserRouter(routes);
function App() { return <RouterProvider router={router} />; }
Components
Modifiers
- @public

function Router

Router: ({
    basename: basenameProp,
    children,
    location: locationProp,
    navigationType,
    navigator,
    static: staticProp,
    unstable_useTransitions,
}: RouterProps) => React.ReactElement | null;

Provides location context for the rest of the app.
Note: You usually won't render a <Router> directly. Instead, you'll render a router that is more specific to your environment such as a BrowserRouter in web browsers or a ServerRouter for server rendering.
Declarative Routers declarative
Parameter props
Props
Parameter
{RouterProps.basename} props.basename n/a
Parameter
{RouterProps.children} props.children n/a
Parameter
{RouterProps.location} props.location n/a
Parameter
{RouterProps.navigationType} props.navigationType n/a
Parameter
{RouterProps.navigator} props.navigator n/a
Parameter
{RouterProps.static} props.static n/a
Parameter
{RouterProps.unstable_useTransitions} props.unstable_useTransitions n/a
Returns
React element for the rendered router or null if the location does not match the props.basename
Modifiers
- @public

function RouterProvider

RouterProvider: ({
    router,
    flushSync: reactDomFlushSyncImpl,
    onError,
    unstable_useTransitions,
}: RouterProviderProps) => React.ReactElement;

Render the UI for the given DataRouter. This component should typically be at the top of an app's element tree.
import { createBrowserRouter } from "react-router"; import { RouterProvider } from "react-router/dom"; import { createRoot } from "react-dom/client"; const router = createBrowserRouter(routes); createRoot(document.getElementById("root")).render( <RouterProvider router={router} /> );
Please note that this component is exported both from react-router and react-router/dom with the only difference being that the latter automatically wires up react-dom's [flushSync](https://react.dev/reference/react-dom/flushSync) implementation. You _almost always_ want to use the version from react-router/dom unless you're running in a non-DOM environment.
Data Routers data
Parameter props
Props
Parameter
{RouterProviderProps.flushSync} props.flushSync n/a
Parameter
{RouterProviderProps.onError} props.onError n/a
Parameter
{RouterProviderProps.router} props.router n/a
Parameter
{RouterProviderProps.unstable_useTransitions} props.unstable_useTransitions n/a
Returns
React element for the rendered router
Modifiers
- @public

function Routes

Routes: ({ children, location }: RoutesProps) => React.ReactElement | null;

Renders a branch of `<Route>`s that best matches the current location. Note that these routes do not participate in [data loading](../../start/framework/route-module#loader), [action](../../start/framework/route-module#action), code splitting, or any other [route module](../../start/framework/route-module) features.
Parameter props
Props
Parameter
{RoutesProps.children} props.children n/a
Parameter
{RoutesProps.location} props.location n/a
Returns
React element for the rendered routes or null if no route matches
Example 1
import { Route, Routes } from "react-router";
<Route index element={} /> <Route path="step-2" element={} /> <Route path="step-3" element={} />
Components
Modifiers
- @public

function Scripts

Scripts: (scriptProps: ScriptsProps) => React.JSX.Element | null;

Renders the client runtime of your app. It should be rendered inside the [<body>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body) of the document.
If server rendering, you can omit <Scripts/> and the app will work as a traditional web app without JavaScript, relying solely on HTML and browser behaviors.
Parameter scriptProps
Additional props to spread onto the [<script>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) tags, such as [crossOrigin](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/crossOrigin), [nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce), etc.
Returns
A collection of React elements for [<script>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) tags
Example 1
import { Scripts } from "react-router";
export default function Root() { return ( ); }
Components framework
Modifiers
- @public

function ScrollRestoration

ScrollRestoration: typeof ScrollRestoration;

Emulates the browser's scroll restoration on location changes. Apps should only render one of these, right before the Scripts component.
import { ScrollRestoration } from "react-router"; export default function Root() { return ( <html> <body> <ScrollRestoration /> <Scripts /> </body> </html> ); }
This component renders an inline <script> to prevent scroll flashing. The nonce prop will be passed down to the script tag to allow CSP nonce usage.
<ScrollRestoration nonce={cspNonce} />
Components framework data
Parameter props
Props
Parameter
{ScrollRestorationProps.getKey} props.getKey n/a
Parameter
{ScriptsProps.nonce} props.nonce n/a
Parameter
{ScrollRestorationProps.storageKey} props.storageKey n/a
Returns
A [<script>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) tag that restores scroll positions on navigation.
Modifiers
- @public

function ServerRouter

ServerRouter: ({ context, url, nonce }: ServerRouterProps) => ReactElement;

The server entry point for a React Router app in Framework Mode. This component is used to generate the HTML in the response from the server. See [entry.server.tsx](../framework-conventions/entry.server.tsx).
Framework Routers framework
Parameter props
Props
Parameter
{ServerRouterProps.context} props.context n/a
Parameter
{ServerRouterProps.nonce} props.nonce n/a
Parameter
{ServerRouterProps.url} props.url n/a
Returns
A React element that represents the server-rendered application.
Modifiers
- @public

function StaticRouter

StaticRouter: ({
    basename,
    children,
    location: locationProp,
}: StaticRouterProps) => React.JSX.Element;

A `<Router>` that may not navigate to any other Location. This is useful on the server where there is no stateful UI.
Declarative Routers declarative
Parameter props
Props
Parameter
{StaticRouterProps.basename} props.basename n/a
Parameter
{StaticRouterProps.children} props.children n/a
Parameter
{StaticRouterProps.location} props.location n/a
Returns
A React element that renders the static `<Router>`
Modifiers
- @public

function StaticRouterProvider

StaticRouterProvider: ({
    context,
    router,
    hydrate,
    nonce,
}: StaticRouterProviderProps) => React.JSX.Element;

A DataRouter that may not navigate to any other Location. This is useful on the server where there is no stateful UI.
Parameter props
Props
Parameter
{StaticRouterProviderProps.context} props.context n/a
Parameter
{StaticRouterProviderProps.hydrate} props.hydrate n/a
Parameter
{StaticRouterProviderProps.nonce} props.nonce n/a
Parameter
{StaticRouterProviderProps.router} props.router n/a
Returns
A React element that renders the static router provider
Example 1
export async function handleRequest(request: Request) { let { query, dataRoutes } = createStaticHandler(routes); let context = await query(request));
if (context instanceof Response) { return context; }
let router = createStaticRouter(dataRoutes, context); return new Response( ReactDOMServer.renderToString(<StaticRouterProvider ... />), { headers: { "Content-Type": "text/html" } } ); }
Data Routers data
Modifiers
- @public

function UNSAFE_AwaitContextProvider

UNSAFE_AwaitContextProvider: (
    props: React.ComponentProps<any>
) => React.FunctionComponentElement<React.ProviderProps<TrackedPromise>>;

function UNSAFE_createBrowserHistory

UNSAFE_createBrowserHistory: (options?: BrowserHistoryOptions) => BrowserHistory;

Browser history stores the location in regular URLs. This is the standard for most web apps, but it requires some configuration on the server to ensure you serve the same app at multiple URLs.
See Also
- https://github.com/remix-run/history/tree/main/docs/api-reference.md#createbrowserhistory

function UNSAFE_createClientRoutes

UNSAFE_createClientRoutes: (
    manifest: RouteManifest<EntryRoute>,
    routeModulesCache: RouteModules,
    initialState: HydrationState | null,
    ssr: boolean,
    isSpaMode: boolean,
    parentId?: string,
    routesByParentId?: Record<string, Omit<EntryRoute, 'children'>[]>,
    needsRevalidation?: Set<string>
) => DataRouteObject[];

function UNSAFE_createClientRoutesWithHMRRevalidationOptOut

UNSAFE_createClientRoutesWithHMRRevalidationOptOut: (
    needsRevalidation: Set<string>,
    manifest: RouteManifest<EntryRoute>,
    routeModulesCache: RouteModules,
    initialState: HydrationState,
    ssr: boolean,
    isSpaMode: boolean
) => DataRouteObject[];

function UNSAFE_createHashHistory

UNSAFE_createHashHistory: (options?: HashHistoryOptions) => HashHistory;

Hash history stores the location in window.location.hash. This makes it ideal for situations where you don't want to send the location to the server for some reason, either because you do cannot configure it or the URL space is reserved for something else.
See Also
- https://github.com/remix-run/history/tree/main/docs/api-reference.md#createhashhistory

function UNSAFE_createMemoryHistory

UNSAFE_createMemoryHistory: (options?: MemoryHistoryOptions) => MemoryHistory;

Memory history stores the current location in memory. It is designed for use in stateful non-browser environments like tests and React Native.

function UNSAFE_createRouter

UNSAFE_createRouter: (init: RouterInit) => Router$1;

Create a router and listen to history POP navigations

function UNSAFE_decodeViaTurboStream

UNSAFE_decodeViaTurboStream: (
    body: ReadableStream<Uint8Array>,
    global: Window | typeof globalThis
) => Promise<{ done: Promise<undefined>; value: unknown }>;

function UNSAFE_deserializeErrors

UNSAFE_deserializeErrors: (
    errors: RouterState['errors']
) => RouterState['errors'];

function UNSAFE_getHydrationData

UNSAFE_getHydrationData: ({
    state,
    routes,
    getRouteInfo,
    location,
    basename,
    isSpaMode,
}: {
    state: {
        loaderData?: Router['state']['loaderData'];
        actionData?: Router['state']['actionData'];
        errors?: Router['state']['errors'];
    };
    routes: DataRouteObject[];
    getRouteInfo: (routeId: string) => {
        clientLoader: ClientLoaderFunction | undefined;
        hasLoader: boolean;
        hasHydrateFallback: boolean;
    };
    location: Path;
    basename: string | undefined;
    isSpaMode: boolean;
}) => HydrationState;

function UNSAFE_getPatchRoutesOnNavigationFunction

UNSAFE_getPatchRoutesOnNavigationFunction: (
    getRouter: () => Router,
    manifest: AssetsManifest,
    routeModules: RouteModules,
    ssr: boolean,
    routeDiscovery: ServerBuild['routeDiscovery'],
    isSpaMode: boolean,
    basename: string | undefined
) => PatchRoutesOnNavigationFunction | undefined;

function UNSAFE_getTurboStreamSingleFetchDataStrategy

UNSAFE_getTurboStreamSingleFetchDataStrategy: (
    getRouter: () => Router,
    manifest: AssetsManifest,
    routeModules: RouteModules,
    ssr: boolean,
    basename: string | undefined,
    trailingSlashAware: boolean
) => DataStrategyFunction;

function UNSAFE_invariant

UNSAFE_invariant: {
    (value: boolean, message?: string): asserts value;
    <T>(value: T, message?: string): asserts value is T;
};

function UNSAFE_mapRouteProperties

UNSAFE_mapRouteProperties: (
    route: RouteObject
) => Partial<RouteObject> & { hasErrorBoundary: boolean };

function UNSAFE_RSCDefaultRootErrorBoundary

UNSAFE_RSCDefaultRootErrorBoundary: ({
    hasRootLayout,
}: {
    hasRootLayout: boolean;
}) => React__default.JSX.Element;

function UNSAFE_shouldHydrateRouteLoader

UNSAFE_shouldHydrateRouteLoader: (
    routeId: string,
    clientLoader: ClientLoaderFunction | undefined,
    hasLoader: boolean,
    isSpaMode: boolean
) => boolean;

function UNSAFE_useFogOFWarDiscovery

UNSAFE_useFogOFWarDiscovery: (
    router: Router,
    manifest: AssetsManifest,
    routeModules: RouteModules,
    ssr: boolean,
    routeDiscovery: ServerBuild['routeDiscovery'],
    isSpaMode: boolean
) => void;

function UNSAFE_useScrollRestoration

UNSAFE_useScrollRestoration: ({
    getKey,
    storageKey,
}?: {
    getKey?: GetScrollRestorationKeyFunction;
    storageKey?: string;
}) => void;

When rendered inside a RouterProvider, will restore scroll positions on navigations

UNSAFE_useScrollRestoration Hooks framework data
Parameter options
Options
Parameter
options.getKey A function that returns a key to use for scroll restoration. This is useful for custom scroll restoration logic, such as using only the pathname so that subsequent navigations to prior paths will restore the scroll. Defaults to location.key.
Parameter
options.storageKey The key to use for storing scroll positions in sessionStorage. Defaults to "react-router-scroll-positions".
Returns
{void}

function UNSAFE_withComponentProps

UNSAFE_withComponentProps: (
    Component: React.ComponentType<{
        params: Readonly<Params<string>>;
        loaderData: any;
        actionData: any;
        matches: UIMatch<unknown, unknown>[];
    }>
) => () => React.ReactElement<
    {
        params: Readonly<Params<string>>;
        loaderData: any;
        actionData: any;
        matches: UIMatch<unknown, unknown>[];
    },
    string | React.JSXElementConstructor<any>
>;

function UNSAFE_WithComponentProps

UNSAFE_WithComponentProps: ({
    children,
}: {
    children: React.ReactElement;
}) => React.ReactElement<any, any>;

function UNSAFE_withErrorBoundaryProps

UNSAFE_withErrorBoundaryProps: (
    ErrorBoundary: React.ComponentType<{
        params: Readonly<Params<string>>;
        loaderData: any;
        actionData: any;
        error: unknown;
    }>
) => () => React.ReactElement<
    {
        params: Readonly<Params<string>>;
        loaderData: any;
        actionData: any;
        error: unknown;
    },
    string | React.JSXElementConstructor<any>
>;

function UNSAFE_WithErrorBoundaryProps

UNSAFE_WithErrorBoundaryProps: ({
    children,
}: {
    children: React.ReactElement;
}) => React.ReactElement<any, any>;

function UNSAFE_withHydrateFallbackProps

UNSAFE_withHydrateFallbackProps: (
    HydrateFallback: React.ComponentType<{
        params: Readonly<Params<string>>;
        loaderData: any;
        actionData: any;
    }>
) => () => React.ReactElement<
    { params: Readonly<Params<string>>; loaderData: any; actionData: any },
    string | React.JSXElementConstructor<any>
>;

function UNSAFE_WithHydrateFallbackProps

UNSAFE_WithHydrateFallbackProps: ({
    children,
}: {
    children: React.ReactElement;
}) => React.ReactElement<any, any>;

function unstable_HistoryRouter

unstable_HistoryRouter: typeof HistoryRouter;

A declarative `<Router>` that accepts a pre-instantiated history object. It's important to note that using your own history object is highly discouraged and may add two versions of the history library to your bundles unless you use the same version of the history library that React Router uses internally.
unstable_HistoryRouter
Declarative Routers declarative
Parameter props
Props
Parameter
{HistoryRouterProps.basename} props.basename n/a
Parameter
{HistoryRouterProps.children} props.children n/a
Parameter
{HistoryRouterProps.history} props.history n/a
Parameter
{HistoryRouterProps.unstable_useTransitions} props.unstable_useTransitions n/a
Returns
A declarative `<Router>` using the provided history implementation for client-side routing.
Modifiers
- @public

function unstable_routeRSCServerRequest

unstable_routeRSCServerRequest: ({
    request,
    serverResponse,
    createFromReadableStream,
    renderHTML,
    hydrate,
}: {
    request: Request;
    serverResponse: Response;
    createFromReadableStream: SSRCreateFromReadableStreamFunction;
    renderHTML: (
        getPayload: () => DecodedPayload,
        options: {
            onError(error: unknown): string | undefined;
            onHeaders(headers: Headers): void;
        }
    ) => ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>;
    hydrate?: boolean;
}) => Promise<Response>;

Routes the incoming [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) to the [RSC](https://react.dev/reference/rsc/server-components) server and appropriately proxies the server response for data / resource requests, or renders to HTML for a document request.
Parameter opts
Options
Parameter
opts.createFromReadableStream Your react-server-dom-xyz/client's createFromReadableStream function, used to decode payloads from the server.
Parameter
opts.serverResponse A Response or partial response generated by the [RSC](https://react.dev/reference/rsc/server-components) handler containing a serialized unstable_RSCPayload.
Parameter
opts.hydrate Whether to hydrate the server response with the RSC payload. Defaults to true.
Parameter
opts.renderHTML A function that renders the unstable_RSCPayload to HTML, usually using a `<RSCStaticRouter>`.
Parameter
opts.request The request to route.
Returns
A [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) that either contains the [RSC](https://react.dev/reference/rsc/server-components) payload for data requests, or renders the HTML for document requests.
Example 1
import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr"; import * as ReactDomServer from "react-dom/server.edge"; import { unstable_RSCStaticRouter as RSCStaticRouter, unstable_routeRSCServerRequest as routeRSCServerRequest, } from "react-router";
routeRSCServerRequest({ request, serverResponse, createFromReadableStream, async renderHTML(getPayload) { const payload = getPayload();
return await renderHTMLToReadableStream( <RSCStaticRouter getPayload={getPayload} />, { bootstrapScriptContent, formState: await payload.formState, } ); }, });
unstable_routeRSCServerRequest
RSC data
Modifiers
- @public

function unstable_RSCStaticRouter

unstable_RSCStaticRouter: ({
    getPayload,
}: RSCStaticRouterProps) => React.JSX.Element | null;

Pre-renders an unstable_RSCPayload to HTML. Usually used in unstable_routeRSCServerRequest's renderHTML callback.
Parameter props
Props
Parameter
{unstable_RSCStaticRouterProps.getPayload} props.getPayload n/a
Returns
A React component that renders the unstable_RSCPayload as HTML.
Example 1
import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr"; import * as ReactDomServer from "react-dom/server.edge"; import { unstable_RSCStaticRouter as RSCStaticRouter, unstable_routeRSCServerRequest as routeRSCServerRequest, } from "react-router";
routeRSCServerRequest({ request, serverResponse, createFromReadableStream, async renderHTML(getPayload) { const payload = getPayload();
return await renderHTMLToReadableStream( <RSCStaticRouter getPayload={getPayload} />, { bootstrapScriptContent, formState: await payload.formState, } ); }, });
unstable_RSCStaticRouter
RSC data
Modifiers
- @public

function unstable_setDevServerHooks

unstable_setDevServerHooks: (devServerHooks: DevServerHooks) => void;

function unstable_usePrompt

unstable_usePrompt: ({
    when,
    message,
}: {
    when: boolean | BlockerFunction;
    message: string;
}) => void;

Wrapper around useBlocker to show a [window.confirm](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm) prompt to users instead of building a custom UI with useBlocker.
The unstable_ flag will not be removed because this technique has a lot of rough edges and behaves very differently (and incorrectly sometimes) across browsers if users click addition back/forward navigations while the confirmation is open. Use at your own risk.
Parameter options
Options
Parameter
options.message The message to show in the confirmation dialog.
Parameter
options.when A boolean or a function that returns a boolean indicating whether to block the navigation. If a function is provided, it will receive an object with currentLocation and nextLocation properties.
Returns
{void}
Example 1
function ImportantForm() { let [value, setValue] = React.useState("");
// Block navigating elsewhere when data has been entered into the input unstable_usePrompt({ message: "Are you sure?", when: ({ currentLocation, nextLocation }) => value !== "" && currentLocation.pathname !== nextLocation.pathname, });
return ( Enter some important data: <input name="data" value={value} onChange={(e) => setValue(e.target.value)} /> Save ); }
unstable_usePrompt
Hooks framework data
Modifiers
- @public

function unstable_useRoute

unstable_useRoute: <Args extends UseRouteArgs>(
    ...args: Args
) => UseRouteResult<Args>;

function useActionData

useActionData: <T = any>() => SerializeFrom<T> | undefined;

Returns the [action](../../start/framework/route-module#action) data from the most recent POST navigation form submission or undefined if there hasn't been one.
Returns
The data returned from the route's [action](../../start/framework/route-module#action) function, or undefined if no [action](../../start/framework/route-module#action) has been called
Example 1
import { Form, useActionData } from "react-router";
export async function action({ request }) { const body = await request.formData(); const name = body.get("visitorsName"); return { message: Hello, ${name} }; }
export default function Invoices() { const data = useActionData(); return ( {data ? data.message : "Waiting..."} ); }
Hooks framework data
Modifiers
- @public

function useAsyncError

useAsyncError: () => unknown;

Returns the rejection value from the closest `<Await>`.
Returns
The error that was thrown in the nearest Await component
Example 1
import { Await, useAsyncError } from "react-router";
function ErrorElement() { const error = useAsyncError(); return ( Uh Oh, something went wrong! {error.message} ); }
// somewhere in your app <Await resolve={promiseThatRejects} errorElement={} />;
Hooks framework data
Modifiers
- @public

function useAsyncValue

useAsyncValue: () => unknown;

Returns the resolved promise value from the closest `<Await>`.
Returns
The resolved value from the nearest Await component
Example 1
function SomeDescendant() { const value = useAsyncValue(); // ... }
// somewhere in your app <Await resolve={somePromise}> ;
Hooks framework data
Modifiers
- @public

function useBeforeUnload

useBeforeUnload: (
    callback: (event: BeforeUnloadEvent) => any,
    options?: { capture?: boolean }
) => void;

Set up a callback to be fired on [Window's beforeunload event](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event).
Hooks
Parameter callback
The callback to be called when the [beforeunload event](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event) is fired.
Parameter options
Options
Parameter
options.capture If true, the event will be captured during the capture phase. Defaults to false.
Returns
{void}
Modifiers
- @public

function useBlocker

useBlocker: (shouldBlock: boolean | BlockerFunction) => Blocker;

Allow the application to block navigations within the SPA and present the user a confirmation dialog to confirm the navigation. Mostly used to avoid using half-filled form data. This does not handle hard-reloads or cross-origin navigations.

The Blocker object returned by the hook has the following properties:

- **state** - unblocked - the blocker is idle and has not prevented any navigation - blocked - the blocker has prevented a navigation - proceeding - the blocker is proceeding through from a blocked navigation - **location** - When in a blocked state, this represents the Location to which we blocked a navigation. When in a proceeding state, this is the location being navigated to after a blocker.proceed() call. - **proceed()** - When in a blocked state, you may call blocker.proceed() to proceed to the blocked location. - **reset()** - When in a blocked state, you may call blocker.reset() to return the blocker to an unblocked state and leave the user at the current location.

Parameter shouldBlock

Either a boolean or a function returning a boolean which indicates whether the navigation should be blocked. The function format receives a single object parameter containing the currentLocation, nextLocation, and historyAction of the potential navigation.

Returns

A Blocker object with state and reset functionality

Example 1

// Boolean version let blocker = useBlocker(value !== "");

// Function version let blocker = useBlocker( ({ currentLocation, nextLocation, historyAction }) => value !== "" && currentLocation.pathname !== nextLocation.pathname );

import { useCallback, useState } from "react";
import { BlockerFunction, useBlocker } from "react-router";

export function ImportantForm() {
  const [value, setValue] = useState("");

  const shouldBlock = useCallback<BlockerFunction>(
    () => value !== "",
    [value]
  );
  const blocker = useBlocker(shouldBlock);

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        setValue("");
        if (blocker.state === "blocked") {
          blocker.proceed();
        }
      }}
    >
      <input
        name="data"
        value={value}
        onChange={(e) => setValue(e.target.value)}
      />

      <button type="submit">Save</button>

      {blocker.state === "blocked" ? (
        <>
          <p style={{ color: "red" }}>
            Blocked the last navigation to
          </p>
          <button
            type="button"
            onClick={() => blocker.proceed()}
          >
            Let me through
          </button>
          <button
            type="button"
            onClick={() => blocker.reset()}
          >
            Keep me here
          </button>
        </>
      ) : blocker.state === "proceeding" ? (
        <p style={{ color: "orange" }}>
          Proceeding through blocked navigation
        </p>
      ) : (
        <p style={{ color: "green" }}>
          Blocker is currently unblocked
        </p>
      )}
    </form>
  );
}

Hooks framework data

Modifiers

@public

function useFetcher

useFetcher: <T = any>({
    key,
}?: {
    key?: string;
}) => FetcherWithComponents<SerializeFrom<T>>;

Useful for creating complex, dynamic user interfaces that require multiple, concurrent data interactions without causing a navigation.
Fetchers track their own, independent state and can be used to load data, submit forms, and generally interact with [action](../../start/framework/route-module#action) and [loader](../../start/framework/route-module#loader) functions.
Parameter options
Options
Parameter
options.key A unique key to identify the fetcher.
By default, useFetcher generates a unique fetcher scoped to that component. If you want to identify a fetcher with your own key such that you can access it from elsewhere in your app, you can do that with the key option:
function SomeComp() { let fetcher = useFetcher({ key: "my-key" }) // ... } // Somewhere else function AnotherComp() { // this will be the same fetcher, sharing the state across the app let fetcher = useFetcher({ key: "my-key" }); // ... }
Returns
A FetcherWithComponents object that contains the fetcher's state, data, and components for submitting forms and loading data.
Example 1
import { useFetcher } from "react-router"
function SomeComponent() { let fetcher = useFetcher()
// states are available on the fetcher fetcher.state // "idle" | "loading" | "submitting" fetcher.data // the data returned from the action or loader
// render a form <fetcher.Form method="post" />
// load data fetcher.load("/some/route")
// submit data fetcher.submit(someFormRef, { method: "post" }) fetcher.submit(someData, { method: "post", encType: "application/json" })
// reset fetcher fetcher.reset() }
Hooks framework data
Modifiers
- @public

function useFetchers

useFetchers: () => (Fetcher & { key: string })[];

Returns an array of all in-flight Fetchers. This is useful for components throughout the app that didn't create the fetchers but want to use their submissions to participate in optimistic UI.
Returns
An array of all in-flight Fetchers, each with a unique key property.
Example 1
import { useFetchers } from "react-router";
function SomeComponent() { const fetchers = useFetchers(); fetchers[0].formData; // FormData fetchers[0].state; // etc. // ... }
Hooks framework data
Modifiers
- @public

function useFormAction

useFormAction: (
    action?: string,
    { relative }?: { relative?: RelativeRoutingType }
) => string;

Resolves the URL to the closest route in the component hierarchy instead of the current URL of the app.
This is used internally by Form to resolve the action to the closest route, but can be used generically as well.
Parameter action
The action to append to the closest route URL. Defaults to the closest route URL.
Parameter options
Options
Parameter
options.relative The relative routing type to use when resolving the action. Defaults to "route".
Returns
The resolved action URL.
Example 1
import { useFormAction } from "react-router";
function SomeComponent() { // closest route URL let action = useFormAction();
// closest route URL + "destroy" let destroyAction = useFormAction("destroy"); }
Hooks framework data
Modifiers
- @public

function useHref

useHref: (to: To, { relative }?: { relative?: RelativeRoutingType }) => string;

Resolves a URL against the current Location.
Parameter to
The path to resolve
Parameter options
Options
Parameter
options.relative Defaults to "route" so routing is relative to the route tree. Set to "path" to make relative routing operate against path segments.
Returns
The resolved href string
Example 1
import { useHref } from "react-router";
function SomeComponent() { let href = useHref("some/where"); // "/resolved/some/where" }
Hooks
Modifiers
- @public

function useInRouterContext

useInRouterContext: () => boolean;

Returns true if this component is a descendant of a Router, useful to ensure a component is used within a Router.
Hooks framework data
Returns
Whether the component is within a Router context
Modifiers
- @public

function useLinkClickHandler

useLinkClickHandler: <E extends Element = HTMLAnchorElement>(
    to: To,
    {
        target,
        replace: replaceProp,
        unstable_mask,
        state,
        preventScrollReset,
        relative,
        viewTransition,
        unstable_defaultShouldRevalidate,
        unstable_useTransitions,
    }?: {
        target?: React.HTMLAttributeAnchorTarget;
        replace?: boolean;
        unstable_mask?: To;
        state?: any;
        preventScrollReset?: boolean;
        relative?: RelativeRoutingType;
        viewTransition?: boolean;
        unstable_defaultShouldRevalidate?: boolean;
        unstable_useTransitions?: boolean;
    }
) => (event: React.MouseEvent<E, MouseEvent>) => void;

Handles the click behavior for router `<Link>` components.This is useful if you need to create custom `<Link>` components with the same click behavior we use in our exported `<Link>`.
Hooks
Parameter to
The URL to navigate to, can be a string or a partial Path.
Parameter options
Options
Parameter
options.preventScrollReset Whether to prevent the scroll position from being reset to the top of the viewport on completion of the navigation when using the ScrollRestoration component. Defaults to false.
Parameter
options.relative The relative routing type to use for the link. Defaults to "route".
Parameter
options.replace Whether to replace the current [History](https://developer.mozilla.org/en-US/docs/Web/API/History) entry instead of pushing a new one. Defaults to false.
Parameter
options.state The state to add to the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) entry for this navigation. Defaults to undefined.
Parameter
options.target The target attribute for the link. Defaults to undefined.
Parameter
options.viewTransition Enables a [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) for this navigation. To apply specific styles during the transition, see useViewTransitionState. Defaults to false.
Parameter
options.unstable_defaultShouldRevalidate Specify the default revalidation behavior for the navigation. Defaults to true.
Parameter
options.unstable_mask Masked location to display in the browser instead of the router location. Defaults to undefined.
Parameter
options.unstable_useTransitions Wraps the navigation in [React.startTransition](https://react.dev/reference/react/startTransition) for concurrent rendering. Defaults to false.
Returns
A click handler function that can be used in a custom Link component.
Modifiers
- @public

function useLoaderData

useLoaderData: <T = any>() => SerializeFrom<T>;

Returns the data from the closest route [loader](../../start/framework/route-module#loader) or [clientLoader](../../start/framework/route-module#clientloader).
Returns
The data returned from the route's [loader](../../start/framework/route-module#loader) or [clientLoader](../../start/framework/route-module#clientloader) function
Example 1
import { useLoaderData } from "react-router";
export async function loader() { return await fakeDb.invoices.findAll(); }
export default function Invoices() { let invoices = useLoaderData<typeof loader>(); // ... }
Hooks framework data
Modifiers
- @public

function useLocation

useLocation: () => Location;

Returns the current Location. This can be useful if you'd like to perform some side effect whenever it changes.
Returns
The current Location object
Example 1
import * as React from 'react' import { useLocation } from 'react-router'
function SomeComponent() { let location = useLocation()
React.useEffect(() => { // Google Analytics ga('send', 'pageview') }, [location]);
return ( // ... ); }
Hooks
Modifiers
- @public

function useMatch

useMatch: <ParamKey extends ParamParseKey<Path>, Path extends string>(
    pattern: PathPattern<Path> | Path
) => PathMatch<ParamKey> | null;

Returns a PathMatch object if the given pattern matches the current URL. This is useful for components that need to know "active" state, e.g. `<NavLink>`.
Hooks
Parameter pattern
The pattern to match against the current Location
Returns
The path match object if the pattern matches, null otherwise
Modifiers
- @public

function useMatches

useMatches: () => UIMatch[];

Returns the active route matches, useful for accessing loaderData for parent/child routes or the route [handle](../../start/framework/route-module#handle) property
Hooks framework data
Returns
An array of UI matches for the current route hierarchy
Modifiers
- @public

function useNavigate

useNavigate: () => NavigateFunction;

Returns a function that lets you navigate programmatically in the browser in response to user interactions or effects.
It's often better to use redirect in [action](../../start/framework/route-module#action)/[loader](../../start/framework/route-module#loader) functions than this hook.
The returned function signature is navigate(to, options?)/navigate(delta) where:
* to can be a string path, a To object, or a number (delta) * options contains options for modifying the navigation * These options work in all modes (Framework, Data, and Declarative): * relative: "route" or "path" to control relative routing logic * replace: Replace the current entry in the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack * state: Optional [history.state](https://developer.mozilla.org/en-US/docs/Web/API/History/state) to include with the new Location * These options only work in Framework and Data modes: * flushSync: Wrap the DOM updates in [ReactDom.flushSync](https://react.dev/reference/react-dom/flushSync) * preventScrollReset: Do not scroll back to the top of the page after navigation * viewTransition: Enable [document.startViewTransition](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) for this navigation
Returns
A navigate function for programmatic navigation
Example 1
import { useNavigate } from "react-router";
function SomeComponent() { let navigate = useNavigate(); return ( <button onClick={() => navigate(-1)}> Go Back ); }
### Navigate to another path
navigate("/some/route"); navigate("/some/route?search=param");
### Navigate with a To object
All properties are optional.
navigate({ pathname: "/some/route", search: "?search=param", hash: "#hash", state: { some: "state" }, });
If you use state, that will be available on the Location object on the next page. Access it with useLocation().state (see useLocation).
### Navigate back or forward in the history stack
// back // often used to close modals navigate(-1); // forward // often used in a multistep wizard workflows navigate(1);
Be cautious with navigate(number). If your application can load up to a route that has a button that tries to navigate forward/back, there may not be a [History`](https://developer.mozilla.org/en-US/docs/Web/API/History) entry to go back or forward to, or it can go somewhere you don't expect (like a different domain).
Only use this if you're sure they will have an entry in the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack to navigate to.
### Replace the current entry in the history stack
This will remove the current entry in the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack, replacing it with a new one, similar to a server side redirect.
navigate("/some/route", { replace: true });
### Prevent Scroll Reset
[MODES: framework, data]

To prevent `<ScrollRestoration>` from resetting the scroll position, use the preventScrollReset option.
navigate("?some-tab=1", { preventScrollReset: true });
For example, if you have a tab interface connected to search params in the middle of a page, and you don't want it to scroll to the top when a tab is clicked.
### Return Type Augmentation
Internally, useNavigate uses a separate implementation when you are in Declarative mode versus Data/Framework mode - the primary difference being that the latter is able to return a stable reference that does not change identity across navigations. The implementation in Data/Framework mode also returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves when the navigation is completed. This means the return type of useNavigate is void | Promise<void>. This is accurate, but can lead to some red squigglies based on the union in the return value:
- If you're using typescript-eslint, you may see errors from [@typescript-eslint/no-floating-promises](https://typescript-eslint.io/rules/no-floating-promises) - In Framework/Data mode, React.use(navigate()) will show a false-positive `Argument of type 'void | Promise' is not assignable to parameter of type 'Usable'` error
The easiest way to work around these issues is to augment the type based on the router you're using:
// If using <BrowserRouter> declare module "react-router" { interface NavigateFunction { (to: To, options?: NavigateOptions): void; (delta: number): void; } } // If using <RouterProvider> or Framework mode declare module "react-router" { interface NavigateFunction { (to: To, options?: NavigateOptions): Promise<void>; (delta: number): Promise<void>; } }
Hooks
Modifiers
- @public

function useNavigation

useNavigation: () => Navigation;

Returns the current Navigation, defaulting to an "idle" navigation when no navigation is in progress. You can use this to render pending UI (like a global spinner) or read [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) from a form navigation.
Returns
The current Navigation object
Example 1
import { useNavigation } from "react-router";
function SomeComponent() { let navigation = useNavigation(); navigation.state; navigation.formData; // etc. }
Hooks framework data
Modifiers
- @public

function useNavigationType

useNavigationType: () => Action;

Returns the current Navigation action which describes how the router came to the current Location, either by a pop, push, or replace on the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack.
Hooks
Returns
The current NavigationType ("POP", "PUSH", or "REPLACE")
Modifiers
- @public

function useOutlet

useOutlet: (context?: unknown) => React.ReactElement | null;

Returns the element for the child route at this level of the route hierarchy. Used internally by `<Outlet>` to render child routes.
Hooks
Parameter context
The context to pass to the outlet
Returns
The child route element or null if no child routes match
Modifiers
- @public

function useOutletContext

useOutletContext: <Context = unknown>() => Context;

Returns the parent route `<Outlet context>`.

Often parent routes manage state or other values you want shared with child routes. You can create your own [context provider](https://react.dev/learn/passing-data-deeply-with-context) if you like, but this is such a common situation that it's built-into `<Outlet>`.

// Parent route
function Parent() {
  const [count, setCount] = React.useState(0);
  return <Outlet context={[count, setCount]} />;
}

// Child route
import { useOutletContext } from "react-router";

function Child() {
  const [count, setCount] = useOutletContext();
  const increment = () => setCount((c) => c + 1);
  return <button onClick={increment}>{count}</button>;
}

If you're using TypeScript, we recommend the parent component provide a custom hook for accessing the context value. This makes it easier for consumers to get nice typings, control consumers, and know who's consuming the context value.

Here's a more realistic example:

import { useState } from "react";
import { Outlet, useOutletContext } from "react-router";

import type { User } from "./types";

type ContextType = { user: User | null };

export default function Dashboard() {
  const [user, setUser] = useState<User | null>(null);

  return (
    <div>
      <h1>Dashboard</h1>
      <Outlet context={{ user } satisfies ContextType} />
    </div>
  );
}

export function useUser() {
  return useOutletContext<ContextType>();
}

import { useUser } from "../dashboard";

export default function DashboardMessages() {
  const { user } = useUser();
  return (
    <div>
      <h2>Messages</h2>
      <p>Hello, {user.name}!</p>
    </div>
  );
}

Hooks

Returns

The context value passed to the parent Outlet component

Modifiers

@public

function useParams

useParams: <
    ParamsOrKey extends string | Record<string, string> = string
>() => Readonly<
    [ParamsOrKey] extends [string] ? Params<ParamsOrKey> : Partial<ParamsOrKey>
>;

Returns an object of key/value-pairs of the dynamic params from the current URL that were matched by the routes. Child routes inherit all params from their parent routes.

Assuming a route pattern like /posts/:postId is matched by /posts/123 then params.postId will be "123".

Returns

An object containing the dynamic route parameters

Example 1

import { useParams } from "react-router";

function SomeComponent() { let params = useParams(); params.postId; }

### Basic Usage

import { useParams } from "react-router";

// given a route like:
<Route path="/posts/:postId" element={<Post />} />;

// or a data route like:
createBrowserRouter([
  {
    path: "/posts/:postId",
    component: Post,
  },
]);

// or in routes.ts
route("/posts/:postId", "routes/post.tsx");

Access the params in a component:

import { useParams } from "react-router";

export default function Post() {
  let params = useParams();
  return <h1>Post: {params.postId}</h1>;
}

### Multiple Params

Patterns can have multiple params:

"/posts/:postId/comments/:commentId";

All will be available in the params object:

import { useParams } from "react-router";

export default function Post() {
  let params = useParams();
  return (
    <h1>
      Post: {params.postId}, Comment: {params.commentId}
    </h1>
  );
}

### Catchall Params

Catchall params are defined with *:

"/files/*";

The matched value will be available in the params object as follows:

import { useParams } from "react-router";

export default function File() {
  let params = useParams();
  let catchall = params["*"];
  // ...
}

You can destructure the catchall param:

export default function File() {
  let { "*": catchall } = useParams();
  console.log(catchall);
}

Hooks

Modifiers

@public

function useResolvedPath

useResolvedPath: (
    to: To,
    { relative }?: { relative?: RelativeRoutingType }
) => Path;

Resolves the pathname of the given to value against the current Location. Similar to useHref, but returns a Path instead of a string.
Parameter to
The path to resolve
Parameter options
Options
Parameter
options.relative Defaults to "route" so routing is relative to the route tree. Set to "path" to make relative routing operate against path segments.
Returns
The resolved Path object with pathname, search, and hash
Example 1
import { useResolvedPath } from "react-router";
function SomeComponent() { // if the user is at /dashboard/profile let path = useResolvedPath("../accounts"); path.pathname; // "/dashboard/accounts" path.search; // "" path.hash; // "" }
Hooks
Modifiers
- @public

function useRevalidator

useRevalidator: () => {
    revalidate: () => Promise<void>;
    state: Router['state']['revalidation'];
};

Revalidate the data on the page for reasons outside of normal data mutations like [Window focus](https://developer.mozilla.org/en-US/docs/Web/API/Window/focus_event) or polling on an interval.
Note that page data is already revalidated automatically after actions. If you find yourself using this for normal CRUD operations on your data in response to user interactions, you're probably not taking advantage of the other APIs like useFetcher, Form, useSubmit that do this automatically.
Returns
An object with a revalidate function and the current revalidation state
Example 1
import { useRevalidator } from "react-router";
function WindowFocusRevalidator() { const revalidator = useRevalidator();
useFakeWindowFocus(() => { revalidator.revalidate(); });
return ( <div hidden={revalidator.state === "idle"}> Revalidating... ); }
Hooks framework data
Modifiers
- @public

function useRouteError

useRouteError: () => unknown;

Accesses the error thrown during an [action](../../start/framework/route-module#action), [loader](../../start/framework/route-module#loader), or component render to be used in a route module [ErrorBoundary](../../start/framework/route-module#errorboundary).
Returns
The error that was thrown during route [loading](../../start/framework/route-module#loader), [action](../../start/framework/route-module#action) execution, or rendering
Example 1
export function ErrorBoundary() { const error = useRouteError(); return {error.message}; }
Hooks framework data
Modifiers
- @public

function useRouteLoaderData

useRouteLoaderData: <T = any>(routeId: string) => SerializeFrom<T> | undefined;

Returns the [loader](../../start/framework/route-module#loader) data for a given route by route ID.
Route IDs are created automatically. They are simply the path of the route file relative to the app folder without the extension.
| Route Filename | Route ID | | ---------------------------- | ---------------------- | | app/root.tsx | "root" | | app/routes/teams.tsx | "routes/teams" | | app/whatever/teams.$id.tsx | "whatever/teams.$id" |
Parameter routeId
The ID of the route to return loader data from
Returns
The data returned from the specified route's [loader](../../start/framework/route-module#loader) function, or undefined if not found
Example 1
import { useRouteLoaderData } from "react-router";
function SomeComponent() { const { user } = useRouteLoaderData("root"); }
// You can also specify your own route ID's manually in your routes.ts file: route("/", "containers/app.tsx", { id: "app" }) useRouteLoaderData("app");
Hooks framework data
Modifiers
- @public

function useRoutes

useRoutes: (
    routes: RouteObject[],
    locationArg?: Partial<Location> | string
) => React.ReactElement | null;

Hook version of `<Routes>` that uses objects instead of components. These objects have the same properties as the component props. The return value of useRoutes is either a valid React element you can use to render the route tree, or null if nothing matched.
Parameter routes
An array of RouteObjects that define the route hierarchy
Parameter locationArg
An optional Location object or pathname string to use instead of the current Location
Returns
A React element to render the matched route, or null if no routes matched
Example 1
import { useRoutes } from "react-router";
function App() { let element = useRoutes([ { path: "/", element: , children: [ { path: "messages", element: , }, { path: "tasks", element: }, ], }, { path: "team", element: }, ]);
return element; }
Hooks
Modifiers
- @public

function useSearchParams

useSearchParams: (
    defaultInit?: URLSearchParamsInit
) => [URLSearchParams, SetURLSearchParams];

Returns a tuple of the current URL's [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) and a function to update them. Setting the search params causes a navigation.
import { useSearchParams } from "react-router"; export function SomeComponent() { const [searchParams, setSearchParams] = useSearchParams(); // ... }
### setSearchParams function
The second element of the tuple is a function that can be used to update the search params. It accepts the same types as defaultInit and will cause a navigation to the new URL.
let [searchParams, setSearchParams] = useSearchParams(); // a search param string setSearchParams("?tab=1"); // a shorthand object setSearchParams({ tab: "1" }); // object keys can be arrays for multiple values on the key setSearchParams({ brand: ["nike", "reebok"] }); // an array of tuples setSearchParams([["tab", "1"]]); // a `URLSearchParams` object setSearchParams(new URLSearchParams("?tab=1"));
It also supports a function callback like React's [setState](https://react.dev/reference/react/useState#setstate):
setSearchParams((searchParams) => { searchParams.set("tab", "2"); return searchParams; });
The function callback version of setSearchParams does not support the [queueing](https://react.dev/reference/react/useState#setstate-parameters) logic that React's setState implements. Multiple calls to setSearchParams in the same tick will not build on the prior value. If you need this behavior, you can use setState manually.
### Notes
Note that searchParams is a stable reference, so you can reliably use it as a dependency in React's [useEffect](https://react.dev/reference/react/useEffect) hooks.
useEffect(() => { console.log(searchParams.get("tab")); }, [searchParams]);
However, this also means it's mutable. If you change the object without calling setSearchParams, its values will change between renders if some other state causes the component to re-render and URL will not reflect the values.
Hooks
Parameter defaultInit
You can initialize the search params with a default value, though it **will not** change the URL on the first render.
// a search param string useSearchParams("?tab=1"); // a shorthand object useSearchParams({ tab: "1" }); // object keys can be arrays for multiple values on the key useSearchParams({ brand: ["nike", "reebok"] }); // an array of tuples useSearchParams([["tab", "1"]]); // a `URLSearchParams` object useSearchParams(new URLSearchParams("?tab=1"));
Returns
A tuple of the current [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) and a function to update them.
Modifiers
- @public

function useSubmit

useSubmit: () => SubmitFunction;

The imperative version of `<Form>` that lets you submit a form from code instead of a user interaction.
Returns
A function that can be called to submit a Form imperatively.
Example 1
import { useSubmit } from "react-router";
function SomeComponent() { const submit = useSubmit(); return ( <Form onChange={(event) => submit(event.currentTarget)} /> ); }
Hooks framework data
Modifiers
- @public

function useViewTransitionState

useViewTransitionState: (
    to: To,
    { relative }?: { relative?: RelativeRoutingType }
) => boolean;

This hook returns true when there is an active [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) to the specified location. This can be used to apply finer-grained styles to elements to further customize the view transition. This requires that view transitions have been enabled for the given navigation via LinkProps.viewTransition (or the Form, submit, or navigate call)
Hooks framework data
Parameter to
The To location to check for an active [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API).
Parameter options
Options
Parameter
options.relative The relative routing type to use when resolving the to location, defaults to "route". See RelativeRoutingType for more details.
Returns
true if there is an active [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) to the specified Location, otherwise false.
Modifiers
- @public

Classes

class RouterContextProvider

class RouterContextProvider {}

Provides methods for writing/reading values in application context in a type-safe way. Primarily for usage with [middleware](../../how-to/middleware).
Example 1
import { createContext, RouterContextProvider } from "react-router";
const userContext = createContext<User | null>(null); const contextProvider = new RouterContextProvider(); contextProvider.set(userContext, getUser()); // ^ Type-safe const user = contextProvider.get(userContext); // ^ User
Utils framework data
Modifiers
- @public

constructor

constructor(init?: Map<RouterContext<unknown>, unknown>);

Create a new RouterContextProvider instance
Parameter init
An optional initial context map to populate the provider with

method get

get: <T>(context: RouterContext<T>) => T;

Access a value from the context. If no value has been set for the context, it will return the context's defaultValue if provided, or throw an error if no defaultValue was set.
Parameter context
The context to get the value for
Returns
The value for the context, or the context's defaultValue if no value was set

method set

set: <C extends RouterContext<unknown>>(
    context: C,
    value: C extends RouterContext<infer T> ? T : never
) => void;

Set a value for the context. If the context already has a value set, this will overwrite it.
Parameter context
The context to set the value for
Parameter value
The value to set for the context
Returns
{void}

class UNSAFE_DataWithResponseInit

class DataWithResponseInit<D> {}

constructor

constructor(data: {}, init?: ResponseInit);

property data

data: {};

property init

init: ResponseInit;

property type

type: string;

class UNSAFE_ErrorResponseImpl

class ErrorResponseImpl implements ErrorResponse {}

constructor

constructor(status: number, statusText: string, data: any, internal?: boolean);

property data

data: any;

property status

status: number;

property statusText

statusText: string;

class UNSAFE_RemixErrorBoundary

class RemixErrorBoundary extends React.Component<
    RemixErrorBoundaryProps,
    RemixErrorBoundaryState
> {}

constructor

constructor(
    props: React.PropsWithChildren<{
        location: Location<any>;
        isOutsideRemixApp?: boolean;
        error?: Error;
    }>
);

method getDerivedStateFromError

static getDerivedStateFromError: (error: Error) => { error: Error };

method getDerivedStateFromProps

static getDerivedStateFromProps: (
    props: React.PropsWithChildren<{
        location: Location<any>;
        isOutsideRemixApp?: boolean;
        error?: Error;
    }>,
    state: RemixErrorBoundaryState
) => { error: Error | null; location: Location<any> };

method render

render: () =>
    | string
    | number
    | boolean
    | React.JSX.Element
    | Iterable<React.ReactNode>
    | null
    | undefined;

Interfaces

interface ActionFunction

interface ActionFunction<Context = DefaultContext> {}

Route action function signature

call signature

(
    args: ActionFunctionArgs<Context>,
    handlerCtx?: unknown
): DataFunctionReturnValue;

interface ActionFunctionArgs

interface ActionFunctionArgs<Context = DefaultContext>
    extends DataFunctionArgs<Context> {}

Arguments passed to action functions

interface AppLoadContext

interface AppLoadContext {}

An object of unknown type for route loaders and actions provided by the server's getLoadContext() function. This is defined as an empty interface specifically so apps can leverage declaration merging to augment this type globally: https://www.typescriptlang.org/docs/handbook/declaration-merging.html

index signature

[key: string]: unknown;

interface AwaitProps

interface AwaitProps<Resolve> {}

Types

property children

children: React.ReactNode | AwaitResolveRenderFunction<Resolve>;

When using a function, the resolved value is provided as the parameter.

<Await resolve={reviewsPromise}>
  {(resolvedReviews) => <Reviews items={resolvedReviews} />}
</Await>

When using React elements, useAsyncValue will provide the resolved value:

<Await resolve={reviewsPromise}>
  <Reviews />
</Await>

function Reviews() {
  const resolvedReviews = useAsyncValue();
  return <div>...</div>;
}

property errorElement

errorElement?: React.ReactNode;

The error element renders instead of the children when the [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) rejects.
<Await errorElement={<div>Oops</div>} resolve={reviewsPromise} > <Reviews /> </Await>
To provide a more contextual error, you can use the useAsyncError in a child component
<Await errorElement={<ReviewsError />} resolve={reviewsPromise} > <Reviews /> </Await> function ReviewsError() { const error = useAsyncError(); return <div>Error loading reviews: {error.message}</div>; }
If you do not provide an errorElement, the rejected value will bubble up to the nearest route-level [ErrorBoundary](../../start/framework/route-module#errorboundary) and be accessible via the useRouteError hook.

property resolve

resolve: Resolve;

Takes a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) returned from a [loader](../../start/framework/route-module#loader) to be resolved and rendered.

import { Await, useLoaderData } from "react-router";

export async function loader() {
  let reviews = getReviews(); // not awaited
  let book = await getBook();
  return {
    book,
    reviews, // this is a promise
  };
}

export default function Book() {
  const {
    book,
    reviews, // this is the same promise
  } = useLoaderData();

  return (
    <div>
      <h1>{book.title}</h1>
      <p>{book.description}</p>
      <React.Suspense fallback={<ReviewsSkeleton />}>
        <Await
          // and is the promise we pass to Await
          resolve={reviews}
        >
          <Reviews />
        </Await>
      </React.Suspense>
    </div>
  );
}

interface BrowserRouterProps

interface BrowserRouterProps {}

Types

property basename

basename?: string;

Application basename

property children

children?: React.ReactNode;

`<Route>` components describing your route configuration

property unstable_useTransitions

unstable_useTransitions?: boolean;

Control whether router state updates are internally wrapped in [React.startTransition](https://react.dev/reference/react/startTransition).
- When left undefined, all router state updates are wrapped in React.startTransition - When set to true, Link and Form navigations will be wrapped in React.startTransition and all router state updates are wrapped in React.startTransition - When set to false, the router will not leverage React.startTransition on any navigations or state changes.
For more information, please see the [docs](https://reactrouter.com/explanation/react-transitions).

property window

window?: Window;

[Window](https://developer.mozilla.org/en-US/docs/Web/API/Window) object override. Defaults to the global window instance

interface ClientOnErrorFunction

interface ClientOnErrorFunction {}

Function signature for client side error handling for loader/actions errors and rendering errors via componentDidCatch

call signature

(
    error: unknown,
    info: {
        location: Location;
        params: Params;
        unstable_pattern: string;
        errorInfo?: React.ErrorInfo;
    }
): void;

interface Cookie {}

A HTTP cookie.
A Cookie is a logical container for metadata about a HTTP cookie; its name and options. But it doesn't contain a value. Instead, it has parse() and serialize() methods that allow a single instance to be reused for parsing/encoding multiple different values.
See Also
- https://remix.run/utils/cookies#cookie-api

readonly expires?: Date;

The Date this cookie expires.
Note: This is calculated at access time using maxAge when no expires option is provided to createCookie().

readonly isSigned: boolean;

True if this cookie uses one or more secrets for verification.

readonly name: string;

The name of the cookie, used in the Cookie and Set-Cookie headers.

parse: (cookieHeader: string | null, options?: ParseOptions) => Promise<any>;

Parses a raw Cookie header and returns the value of this cookie or null if it's not present.

serialize: (value: any, options?: SerializeOptions) => Promise<string>;

Serializes the given value to a string and returns the Set-Cookie header.

interface CookieSignatureOptions

interface CookieSignatureOptions {}

property secrets

secrets?: string[];

An array of secrets that may be used to sign/unsign the value of a cookie.
The array makes it easy to rotate secrets. New secrets should be added to the beginning of the array. cookie.serialize() will always use the first value in the array, but cookie.parse() may use any of them so that cookies that were signed with older secrets still work.

interface DataRouteMatch

interface DataRouteMatch extends RouteMatch<string, DataRouteObject> {}

interface DataRouter

interface Router$1 {}

A Router instance manages all navigation and data loading/mutations

method createHref

createHref: (location: Location | URL) => string;

PRIVATE - DO NOT USE
Utility function to create an href for the given location
Parameter location

method deleteBlocker

deleteBlocker: (key: string) => void;

PRIVATE - DO NOT USE
Delete a navigation blocker
Parameter key
The identifier for the blocker

method deleteFetcher

deleteFetcher: (key: string) => void;

PRIVATE - DO NOT USE
Delete the fetcher for a given key
Parameter key

method dispose

dispose: () => void;

PRIVATE - DO NOT USE
Cleanup listeners and abort any in-progress loads

method enableScrollRestoration

enableScrollRestoration: (
    savedScrollPositions: Record<string, number>,
    getScrollPosition: GetScrollPositionFunction,
    getKey?: GetScrollRestorationKeyFunction
) => () => void;

PRIVATE - DO NOT USE
Enable scroll restoration behavior in the router
Parameter savedScrollPositions
Object that will manage positions, in case it's being restored from sessionStorage
Parameter getScrollPosition
Function to get the active Y scroll position
Parameter getKey
Function to get the key to use for restoration

method encodeLocation

encodeLocation: (to: To) => Path;

PRIVATE - DO NOT USE
Utility function to URL encode a destination path according to the internal history implementation
Parameter to

method fetch

fetch: (
    key: string,
    routeId: string,
    href: string | null,
    opts?: RouterFetchOptions
) => Promise<void>;

PRIVATE - DO NOT USE
Trigger a fetcher load/submission
Parameter key
Fetcher key
Parameter routeId
Route that owns the fetcher
Parameter href
href to fetch
Parameter opts
Fetcher options, (method, submission, etc.)

method getBlocker

getBlocker: (key: string, fn: BlockerFunction) => Blocker;

PRIVATE - DO NOT USE
Get a navigation blocker
Parameter key
The identifier for the blocker
Parameter fn
The blocker function implementation

method getFetcher

getFetcher: <TData = any>(key: string) => Fetcher<TData>;

PRIVATE - DO NOT USE
Get/create a fetcher for the given key
Parameter key

method initialize

initialize: () => Router$1;

PRIVATE - DO NOT USE
Initialize the router, including adding history listeners and kicking off initial data fetches. Returns a function to cleanup listeners and abort any in-progress loads

method navigate

navigate: {
    (to: number): Promise<void>;
    (to: To, opts?: RouterNavigateOptions): Promise<void>;
};

PRIVATE - DO NOT USE
Navigate forward/backward in the history stack
Parameter to
Delta to move in the history stack
Navigate to the given path
Parameter to
Path to navigate to
Parameter opts
Navigation options (method, submission, etc.)

method patchRoutes

patchRoutes: (
    routeId: string | null,
    children: AgnosticRouteObject[],
    unstable_allowElementMutations?: boolean
) => void;

PRIVATE DO NOT USE
Patch additional children routes into an existing parent route
Parameter routeId
The parent route id or a callback function accepting patch to perform batch patching
Parameter children
The additional children routes
Parameter unstable_allowElementMutations
Allow mutation or route elements on existing routes. Intended for RSC-usage only.

method revalidate

revalidate: () => Promise<void>;

PRIVATE - DO NOT USE
Trigger a revalidation of all current route loaders and fetcher loads

subscribe: (fn: RouterSubscriber) => () => void;

PRIVATE - DO NOT USE
Subscribe to router.state updates
Parameter fn
function to call with the new state

index signature

get basename(): RouterInit['basename'];

PRIVATE - DO NOT USE
Return the basename for the router

index signature

get future(): FutureConfig;

PRIVATE - DO NOT USE
Return the future config for the router

index signature

get state(): RouterState;

PRIVATE - DO NOT USE
Return the current state of the router

index signature

get routes(): AgnosticDataRouteObject[];

PRIVATE - DO NOT USE
Return the routes for this router instance

index signature

get window(): RouterInit['window'];

PRIVATE - DO NOT USE
Return the window associated with the router

interface DataStrategyFunction

interface DataStrategyFunction<Context = DefaultContext> {}

call signature

(args: DataStrategyFunctionArgs<Context>): Promise<
    Record<string, DataStrategyResult>
>;

interface DataStrategyFunctionArgs

interface DataStrategyFunctionArgs<Context = DefaultContext>
    extends DataFunctionArgs<Context> {}

property fetcherKey

fetcherKey: string | null;

The key of the fetcher we are calling dataStrategy for, otherwise null for navigational executions

property matches

matches: DataStrategyMatch[];

Matches for this route extended with Data strategy APIs

property runClientMiddleware

runClientMiddleware: (
    cb: DataStrategyFunction<Context>
) => Promise<Record<string, DataStrategyResult>>;

interface DataStrategyMatch

interface DataStrategyMatch
    extends AgnosticRouteMatch<string, AgnosticDataRouteObject> {}

property resolve

resolve: (
    handlerOverride?: (
        handler: (ctx?: unknown) => DataFunctionReturnValue
    ) => DataFunctionReturnValue
) => Promise<DataStrategyResult>;

An async function that will resolve any route.lazy implementations and execute the route's handler (if necessary), returning a DataStrategyResult
- Calling match.resolve does not mean you're calling the [action](https://reactrouter.com/docs/start/data/route-object#action)/[loader](https://reactrouter.com/docs/start/data/route-object#loader) (the "handler") - resolve will only call the handler internally if needed _and_ if you don't pass your own handlerOverride function parameter - It is safe to call match.resolve for all matches, even if they have shouldLoad=false, and it will no-op if no loading is required - You should generally always call match.resolve() for shouldLoad:true routes to ensure that any route.lazy implementations are processed - See the examples below for how to implement custom handler execution via match.resolve

property shouldLoad

shouldLoad: boolean;

Deprecated
Deprecated in favor of shouldCallHandler
A boolean value indicating whether this route handler should be called in this pass.
The matches array always includes _all_ matched routes even when only _some_ route handlers need to be called so that things like middleware can be implemented.
shouldLoad is usually only interesting if you are skipping the route handler entirely and implementing custom handler logic - since it lets you determine if that custom logic should run for this route or not.
For example: - If you are on /parent/child/a and you navigate to /parent/child/b - you'll get an array of three matches ([parent, child, b]), but only b will have shouldLoad=true because the data for parent and child is already loaded - If you are on /parent/child/a and you submit to a's [action](https://reactrouter.com/docs/start/data/route-object#action), then only a will have shouldLoad=true for the action execution of dataStrategy - After the [action](https://reactrouter.com/docs/start/data/route-object#action), dataStrategy will be called again for the [loader](https://reactrouter.com/docs/start/data/route-object#loader) revalidation, and all matches will have shouldLoad=true (assuming no custom shouldRevalidate implementations)

property shouldRevalidateArgs

shouldRevalidateArgs: ShouldRevalidateFunctionArgs | null;

Arguments passed to the shouldRevalidate function for this loader execution. Will be null if this is not a revalidating loader DataStrategyMatch.

method shouldCallHandler

shouldCallHandler: (defaultShouldRevalidate?: boolean) => boolean;

Determine if this route's handler should be called during this dataStrategy execution. Calling it with no arguments will leverage the default revalidation behavior. You can pass your own defaultShouldRevalidate value if you wish to change the default revalidation behavior with your dataStrategy.
Parameter defaultShouldRevalidate
defaultShouldRevalidate override value (optional)

interface DataStrategyResult

interface DataStrategyResult {}

Result from a loader or action called via dataStrategy

property result

result: unknown;

property type

type: 'data' | 'error';

interface DOMRouterOpts

interface DOMRouterOpts {}

Data Routers

property basename

basename?: string;

Basename path for the application.

property dataStrategy

dataStrategy?: DataStrategyFunction;

Override the default data strategy of running loaders in parallel - see the [docs](../../how-to/data-strategy) for more information.

let router = createBrowserRouter(routes, {
  async dataStrategy({
    matches,
    request,
    runClientMiddleware,
  }) {
    const matchesToLoad = matches.filter((m) =>
      m.shouldCallHandler(),
    );

    const results: Record<string, DataStrategyResult> = {};
    await runClientMiddleware(() =>
      Promise.all(
        matchesToLoad.map(async (match) => {
          results[match.route.id] = await match.resolve();
        }),
      ),
    );
    return results;
  },
});

property future

future?: Partial<FutureConfig$1>;

Future flags to enable for the router.

property getContext

getContext?: RouterInit['getContext'];

A function that returns an RouterContextProvider instance which is provided as the context argument to client [action](../../start/data/route-object#action)s, [loader](../../start/data/route-object#loader)s and [middleware](../../how-to/middleware). This function is called to generate a fresh context instance on each navigation or fetcher call.
import { createContext, RouterContextProvider, } from "react-router"; const apiClientContext = createContext<APIClient>(); function createBrowserRouter(routes, { getContext() { let context = new RouterContextProvider(); context.set(apiClientContext, getApiClient()); return context; } })

property hydrationData

hydrationData?: HydrationState;

When Server-Rendering and opting-out of automatic hydration, the hydrationData option allows you to pass in hydration data from your server-render. This will almost always be a subset of data from the StaticHandlerContext value you get back from the StaticHandler's query method:
const router = createBrowserRouter(routes, { hydrationData: { loaderData: { // [routeId]: serverLoaderData }, // may also include `errors` and/or `actionData` }, });
**Partial Hydration Data**
You will almost always include a complete set of loaderData to hydrate a server-rendered app. But in advanced use-cases (such as Framework Mode's [clientLoader](../../start/framework/route-module#clientLoader)), you may want to include loaderData for only some routes that were loaded/rendered on the server. This allows you to hydrate _some_ of the routes (such as the app layout/shell) while showing a HydrateFallback component and running the [loader](../../start/data/route-object#loader)s for other routes during hydration.
A route [loader](../../start/data/route-object#loader) will run during hydration in two scenarios:
1. No hydration data is provided In these cases the HydrateFallback component will render on initial hydration 2. The loader.hydrate property is set to true This allows you to run the [loader](../../start/data/route-object#loader) even if you did not render a fallback on initial hydration (i.e., to prime a cache with hydration data)
const router = createBrowserRouter( [ { id: "root", loader: rootLoader, Component: Root, children: [ { id: "index", loader: indexLoader, HydrateFallback: IndexSkeleton, Component: Index, }, ], }, ], { hydrationData: { loaderData: { root: "ROOT DATA", // No index data provided }, }, } );

property patchRoutesOnNavigation

patchRoutesOnNavigation?: PatchRoutesOnNavigationFunction;

Lazily define portions of the route tree on navigations. See PatchRoutesOnNavigationFunction.
By default, React Router wants you to provide a full route tree up front via createBrowserRouter(routes). This allows React Router to perform synchronous route matching, execute loaders, and then render route components in the most optimistic manner without introducing waterfalls. The tradeoff is that your initial JS bundle is larger by definition — which may slow down application start-up times as your application grows.
To combat this, we introduced [route.lazy](../../start/data/route-object#lazy) in [v6.9.0](https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#v690) which lets you lazily load the route _implementation_ ([loader](../../start/data/route-object#loader), [Component](../../start/data/route-object#Component), etc.) while still providing the route _definition_ aspects up front (path, index, etc.). This is a good middle ground. React Router still knows about your route definitions (the lightweight part) up front and can perform synchronous route matching, but then delay loading any of the route implementation aspects (the heavier part) until the route is actually navigated to.
In some cases, even this doesn't go far enough. For huge applications, providing all route definitions up front can be prohibitively expensive. Additionally, it might not even be possible to provide all route definitions up front in certain Micro-Frontend or Module-Federation architectures.
This is where patchRoutesOnNavigation comes in ([RFC](https://github.com/remix-run/react-router/discussions/11113)). This API is for advanced use-cases where you are unable to provide the full route tree up-front and need a way to lazily "discover" portions of the route tree at runtime. This feature is often referred to as ["Fog of War"](https://en.wikipedia.org/wiki/Fog_of_war), because similar to how video games expand the "world" as you move around - the router would be expanding its routing tree as the user navigated around the app - but would only ever end up loading portions of the tree that the user visited.
patchRoutesOnNavigation will be called anytime React Router is unable to match a path. The arguments include the path, any partial matches, and a patch function you can call to patch new routes into the tree at a specific location. This method is executed during the loading portion of the navigation for GET requests and during the submitting portion of the navigation for non-GET requests.
Example patchRoutesOnNavigation Use Cases
**Patching children into an existing route**
```tsx const router = createBrowserRouter( [ { id: "root", path: "/", Component: RootComponent, }, ], { async patchRoutesOnNavigation({ patch, path }) { if (path === "/a") { // Load/patch the a route as a child of the route with id root let route = await getARoute(); // ^ { path: 'a', Component: A } patch("root", [route]); } }, } ); ```
In the above example, if the user clicks a link to /a, React Router won't match any routes initially and will call patchRoutesOnNavigation with a path = "/a" and a matches array containing the root route match. By calling patch('root', [route]), the new route will be added to the route tree as a child of the root route and React Router will perform matching on the updated routes. This time it will successfully match the /a path and the navigation will complete successfully.
**Patching new root-level routes**
If you need to patch a new route to the top of the tree (i.e., it doesn't have a parent), you can pass null as the routeId:
```tsx const router = createBrowserRouter( [ { id: "root", path: "/", Component: RootComponent, }, ], { async patchRoutesOnNavigation({ patch, path }) { if (path === "/root-sibling") { // Load/patch the /root-sibling route as a sibling of the root route let route = await getRootSiblingRoute(); // ^ { path: '/root-sibling', Component: RootSibling } patch(null, [route]); } }, } ); ```
**Patching subtrees asynchronously**
You can also perform asynchronous matching to lazily fetch entire sections of your application:
```tsx let router = createBrowserRouter( [ { path: "/", Component: Home, }, ], { async patchRoutesOnNavigation({ patch, path }) { if (path.startsWith("/dashboard")) { let children = await import("./dashboard"); patch(null, children); } if (path.startsWith("/account")) { let children = await import("./account"); patch(null, children); } }, } ); ```
If in-progress execution of patchRoutesOnNavigation is interrupted by a later navigation, then any remaining patch calls in the interrupted execution will not update the route tree because the operation was cancelled.
**Co-locating route discovery with route definition**
If you don't wish to perform your own pseudo-matching, you can leverage the partial matches array and the [handle](../../start/data/route-object#handle) field on a route to keep the children definitions co-located:
```tsx let router = createBrowserRouter( [ { path: "/", Component: Home, }, { path: "/dashboard", children: [ { // If we want to include /dashboard in the critical routes, we need to // also include it's index route since patchRoutesOnNavigation will not be // called on a navigation to /dashboard because it will have successfully // matched the /dashboard parent route index: true, // ... }, ], handle: { lazyChildren: () => import("./dashboard"), }, }, { path: "/account", children: [ { index: true, // ... }, ], handle: { lazyChildren: () => import("./account"), }, }, ], { async patchRoutesOnNavigation({ matches, patch }) { let leafRoute = matches[matches.length - 1]?.route; if (leafRoute?.handle?.lazyChildren) { let children = await leafRoute.handle.lazyChildren(); patch(leafRoute.id, children); } }, } ); ```
**A note on routes with parameters**
Because React Router uses ranked routes to find the best match for a given path, there is an interesting ambiguity introduced when only a partial route tree is known at any given point in time. If we match a fully static route such as path: "/about/contact-us" then we know we've found the right match since it's composed entirely of static URL segments. Thus, we do not need to bother asking for any other potentially higher-scoring routes.
However, routes with parameters (dynamic or splat) can't make this assumption because there might be a not-yet-discovered route that scores higher. Consider a full route tree such as:
```tsx // Assume this is the full route tree for your app const routes = [ { path: "/", Component: Home, }, { id: "blog", path: "/blog", Component: BlogLayout, children: [ { path: "new", Component: NewPost }, { path: ":slug", Component: BlogPost }, ], }, ]; ```
And then assume we want to use patchRoutesOnNavigation to fill this in as the user navigates around:
```tsx // Start with only the index route const router = createBrowserRouter( [ { path: "/", Component: Home, }, ], { async patchRoutesOnNavigation({ patch, path }) { if (path === "/blog/new") { patch("blog", [ { path: "new", Component: NewPost, }, ]); } else if (path.startsWith("/blog")) { patch("blog", [ { path: ":slug", Component: BlogPost, }, ]); } }, } ); ```
If the user were to a blog post first (i.e., /blog/my-post) we would patch in the :slug route. Then, if the user navigated to /blog/new to write a new post, we'd match /blog/:slug but it wouldn't be the _right_ match! We need to call patchRoutesOnNavigation just in case there exists a higher-scoring route we've not yet discovered, which in this case there is.
So, anytime React Router matches a path that contains at least one param, it will call patchRoutesOnNavigation and match routes again just to confirm it has found the best match.
If your patchRoutesOnNavigation implementation is expensive or making side effect [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) calls to a backend server, you may want to consider tracking previously seen routes to avoid over-fetching in cases where you know the proper route has already been found. This can usually be as simple as maintaining a small cache of prior path values for which you've already patched in the right routes:
```tsx let discoveredRoutes = new Set();
const router = createBrowserRouter(routes, { async patchRoutesOnNavigation({ patch, path }) { if (discoveredRoutes.has(path)) { // We've seen this before so nothing to patch in and we can let the router // use the routes it already knows about return; }
discoveredRoutes.add(path);
// ... patch routes in accordingly }, }); ```

property unstable_instrumentations

unstable_instrumentations?: unstable_ClientInstrumentation[];

Array of instrumentation objects allowing you to instrument the router and individual routes prior to router initialization (and on any subsequently added routes via route.lazy or patchRoutesOnNavigation). This is mostly useful for observability such as wrapping navigations, fetches, as well as route loaders/actions/middlewares with logging and/or performance tracing. See the [docs](../../how-to/instrumentation) for more information.

let router = createBrowserRouter(routes, {
  unstable_instrumentations: [logging]
});


let logging = {
  router({ instrument }) {
    instrument({
      navigate: (impl, info) => logExecution(`navigate ${info.to}`, impl),
      fetch: (impl, info) => logExecution(`fetch ${info.to}`, impl)
    });
  },
  route({ instrument, id }) {
    instrument({
      middleware: (impl, info) => logExecution(
        `middleware ${info.request.url} (route ${id})`,
        impl
      ),
      loader: (impl, info) => logExecution(
        `loader ${info.request.url} (route ${id})`,
        impl
      ),
      action: (impl, info) => logExecution(
        `action ${info.request.url} (route ${id})`,
        impl
      ),
    })
  }
};

async function logExecution(label: string, impl: () => Promise<void>) {
  let start = performance.now();
  console.log(`start ${label}`);
  await impl();
  let duration = Math.round(performance.now() - start);
  console.log(`end ${label} (${duration}ms)`);
}

property window

window?: Window;

[Window](https://developer.mozilla.org/en-US/docs/Web/API/Window) object override. Defaults to the global window instance.

interface EntryContext

interface EntryContext extends FrameworkContextObject {}

property serverHandoffStream

serverHandoffStream?: ReadableStream<Uint8Array>;

property staticHandlerContext

staticHandlerContext: StaticHandlerContext;

interface FetcherFormProps

interface FetcherFormProps extends SharedFormProps {}

Form props available to fetchers Types

interface FetcherSubmitFunction

interface FetcherSubmitFunction {}

Submits a fetcher [<form>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) to the server without reloading the page.

call signature

(
    /**
     * Can be multiple types of elements and objects
     *
     * **[`HTMLFormElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement)**
     *
     * ```tsx
     * <fetcher.Form
     *   onSubmit={(event) => {
     *     fetcher.submit(event.currentTarget);
     *   }}
     * />
     * ```
     *
     * **[`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)**
     *
     * ```tsx
     * const formData = new FormData();
     * formData.append("myKey", "myValue");
     * fetcher.submit(formData, { method: "post" });
     * ```
     *
     * **Plain object that will be serialized as [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)**
     *
     * ```tsx
     * fetcher.submit({ myKey: "myValue" }, { method: "post" });
     * ```
     *
     * **Plain object that will be serialized as JSON**
     *
     * ```tsx
     * fetcher.submit(
     *   { myKey: "myValue" },
     *   { method: "post", encType: "application/json" }
     * );
     * ```
     */
    target: SubmitTarget,
    options?: FetcherSubmitOptions
): Promise<void>;

interface FetcherSubmitOptions

interface FetcherSubmitOptions extends SharedSubmitOptions {}

Submit options available to fetchers

interface FormProps

interface FormProps extends SharedFormProps {}

Form props available to navigations Types

property discover

discover?: DiscoverBehavior;

Defines the form [lazy route discovery](../../explanation/lazy-route-discovery) behavior.
- **render** — default, discover the route when the form renders - **none** — don't eagerly discover, only discover if the form is submitted
<Form /> // default ("render") <Form discover="render" /> <Form discover="none" />

property fetcherKey

fetcherKey?: string;

Indicates a specific fetcherKey to use when using navigate={false} so you can pick up the fetcher's state in a different component in a useFetcher.

property navigate

navigate?: boolean;

When false, skips the navigation and submits via a fetcher internally. This is essentially a shorthand for useFetcher + <fetcher.Form> where you don't care about the resulting data in this component.

property reloadDocument

reloadDocument?: boolean;

Forces a full document navigation instead of client side routing and data fetch.

property replace

replace?: boolean;

Replaces the current entry in the browser [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack when the form navigates. Use this if you don't want the user to be able to click "back" to the page with the form on it.

property state

state?: any;

State object to add to the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack entry for this navigation

property viewTransition

viewTransition?: boolean;

Enables a [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) for this navigation. To apply specific styles during the transition, see useViewTransitionState.

interface Future

interface Future {}

An augmentable interface users can modify in their app-code to opt into future-flag-specific types

interface GetScrollPositionFunction

interface GetScrollPositionFunction {}

Function signature for determining the current scroll position

call signature

(): number;

interface GetScrollRestorationKeyFunction

interface GetScrollRestorationKeyFunction {}

Function signature for determining the key to be used in scroll restoration for a given location

call signature

(location: Location, matches: UIMatch[]): string | null;

interface HandleDataRequestFunction

interface HandleDataRequestFunction {}

call signature

(
    response: Response,
    args: {
        request: LoaderFunctionArgs['request'] | ActionFunctionArgs['request'];
        context: LoaderFunctionArgs['context'] | ActionFunctionArgs['context'];
        params: LoaderFunctionArgs['params'] | ActionFunctionArgs['params'];
    }
): Promise<Response> | Response;

interface HandleDocumentRequestFunction

interface HandleDocumentRequestFunction {}

call signature

(
    request: Request,
    responseStatusCode: number,
    responseHeaders: Headers,
    context: EntryContext,
    loadContext: MiddlewareEnabled extends true
        ? RouterContextProvider
        : AppLoadContext
): Promise<Response> | Response;

interface HandleErrorFunction

interface HandleErrorFunction {}

call signature

(
    error: unknown,
    args: {
        request: LoaderFunctionArgs['request'] | ActionFunctionArgs['request'];
        context: LoaderFunctionArgs['context'] | ActionFunctionArgs['context'];
        params: LoaderFunctionArgs['params'] | ActionFunctionArgs['params'];
    }
): void;

interface HashRouterProps

interface HashRouterProps {}

Types

property basename

basename?: string;

Application basename

property children

children?: React.ReactNode;

`<Route>` components describing your route configuration

property unstable_useTransitions

unstable_useTransitions?: boolean;

Control whether router state updates are internally wrapped in [React.startTransition](https://react.dev/reference/react/startTransition).
- When left undefined, all router state updates are wrapped in React.startTransition - When set to true, Link and Form navigations will be wrapped in React.startTransition and all router state updates are wrapped in React.startTransition - When set to false, the router will not leverage React.startTransition on any navigations or state changes.
For more information, please see the [docs](https://reactrouter.com/explanation/react-transitions).

property window

window?: Window;

[Window](https://developer.mozilla.org/en-US/docs/Web/API/Window) object override. Defaults to the global window instance

interface HeadersFunction

interface HeadersFunction {}

A function that returns HTTP headers to be used for a route. These headers will be merged with (and take precedence over) headers from parent routes.

call signature

(args: HeadersArgs): Headers | HeadersInit;

interface HistoryRouterProps

interface HistoryRouterProps {}

Types

property basename

basename?: string;

Application basename

property children

children?: React.ReactNode;

`<Route>` components describing your route configuration

property history

history: History;

A History implementation for use by the router

property unstable_useTransitions

unstable_useTransitions?: boolean;

Control whether router state updates are internally wrapped in [React.startTransition](https://react.dev/reference/react/startTransition).
- When left undefined, all router state updates are wrapped in React.startTransition - When set to true, Link and Form navigations will be wrapped in React.startTransition and all router state updates are wrapped in React.startTransition - When set to false, the router will not leverage React.startTransition on any navigations or state changes.
For more information, please see the [docs](https://reactrouter.com/explanation/react-transitions).

interface IndexRouteObject

interface IndexRouteObject {}

property action

action?: AgnosticIndexRouteObject['action'];

property caseSensitive

caseSensitive?: AgnosticIndexRouteObject['caseSensitive'];

property children

children?: undefined;

property Component

Component?: React.ComponentType | null;

property element

element?: React.ReactNode | null;

property ErrorBoundary

ErrorBoundary?: React.ComponentType | null;

property errorElement

errorElement?: React.ReactNode | null;

property handle

handle?: AgnosticIndexRouteObject['handle'];

property hasErrorBoundary

hasErrorBoundary?: AgnosticIndexRouteObject['hasErrorBoundary'];

property HydrateFallback

HydrateFallback?: React.ComponentType | null;

property hydrateFallbackElement

hydrateFallbackElement?: React.ReactNode | null;

property id

id?: AgnosticIndexRouteObject['id'];

property index

index: true;

property lazy

lazy?: LazyRouteDefinition<RouteObject>;

property loader

loader?: AgnosticIndexRouteObject['loader'];

property middleware

middleware?: AgnosticIndexRouteObject['middleware'];

property path

path?: AgnosticIndexRouteObject['path'];

property shouldRevalidate

shouldRevalidate?: AgnosticIndexRouteObject['shouldRevalidate'];

interface IndexRouteProps

interface IndexRouteProps {}

Types

property action

action?: IndexRouteObject['action'];

The route action. See [action](../../start/data/route-object#action).

property caseSensitive

caseSensitive?: IndexRouteObject['caseSensitive'];

Whether the path should be case-sensitive. Defaults to false.

property children

children?: undefined;

Child Route components

property Component

Component?: React.ComponentType | null;

The React Component to render when this route matches. Mutually exclusive with element.

property element

element?: React.ReactNode | null;

The React element to render when this Route matches. Mutually exclusive with Component.

property ErrorBoundary

ErrorBoundary?: React.ComponentType | null;

The React Component to render at this route if an error occurs. Mutually exclusive with errorElement.

property errorElement

errorElement?: React.ReactNode | null;

The React element to render at this route if an error occurs. Mutually exclusive with ErrorBoundary.

property handle

handle?: IndexRouteObject['handle'];

The route handle.

property hasErrorBoundary

hasErrorBoundary?: IndexRouteObject['hasErrorBoundary'];

property HydrateFallback

HydrateFallback?: React.ComponentType | null;

The React Component to render while this router is loading data. Mutually exclusive with hydrateFallbackElement.

property hydrateFallbackElement

hydrateFallbackElement?: React.ReactNode | null;

The React element to render while this router is loading data. Mutually exclusive with HydrateFallback.

property id

id?: IndexRouteObject['id'];

The unique identifier for this route (for use with DataRouters)

property index

index: true;

Whether this is an index route.

property lazy

lazy?: LazyRouteFunction<IndexRouteObject>;

A function that returns a promise that resolves to the route object. Used for code-splitting routes. See [lazy](../../start/data/route-object#lazy).

property loader

loader?: IndexRouteObject['loader'];

The route loader. See [loader](../../start/data/route-object#loader).

property middleware

middleware?: IndexRouteObject['middleware'];

The route middleware. See [middleware](../../start/data/route-object#middleware).

property path

path?: IndexRouteObject['path'];

The path pattern to match. If unspecified or empty, then this becomes a layout route.

property shouldRevalidate

shouldRevalidate?: IndexRouteObject['shouldRevalidate'];

The route shouldRevalidate function. See [shouldRevalidate](../../start/data/route-object#shouldRevalidate).

interface LayoutRouteProps

interface LayoutRouteProps extends PathRouteProps {}

Types

interface LazyRouteFunction

interface LazyRouteFunction<R extends AgnosticRouteObject> {}

lazy() function to load a route definition, which can add non-matching related properties to a route

call signature

(): Promise<
    Omit<R, UnsupportedLazyRouteFunctionKey> &
        Partial<Record<UnsupportedLazyRouteFunctionKey, never>>
>;

interface LinkProps

interface LinkProps
    extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {}

Types

property discover

discover?: DiscoverBehavior;

Defines the link [lazy route discovery](../../explanation/lazy-route-discovery) behavior.
- **render** — default, discover the route when the link renders - **none** — don't eagerly discover, only discover if the link is clicked
<Link /> // default ("render") <Link discover="render" /> <Link discover="none" />

property prefetch

prefetch?: PrefetchBehavior;

Defines the data and module prefetching behavior for the link.
<Link /> // default <Link prefetch="none" /> <Link prefetch="intent" /> <Link prefetch="render" /> <Link prefetch="viewport" />
- **none** — default, no prefetching - **intent** — prefetches when the user hovers or focuses the link - **render** — prefetches when the link renders - **viewport** — prefetches when the link is in the viewport, very useful for mobile
Prefetching is done with HTML [<link rel="prefetch">](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) tags. They are inserted after the link.
<a href="..." /> <a href="..." /> <link rel="prefetch" /> // might conditionally render
Because of this, if you are using nav :last-child you will need to use nav :last-of-type so the styles don't conditionally fall off your last link (and any other similar selectors).

property preventScrollReset

preventScrollReset?: boolean;

Prevents the scroll position from being reset to the top of the window when the link is clicked and the app is using ScrollRestoration. This only prevents new locations resetting scroll to the top, scroll position will be restored for back/forward button navigation.
<Link to="?tab=one" preventScrollReset />

property relative

relative?: RelativeRoutingType;

Defines the relative path behavior for the link.
<Link to=".." /> // default: "route" <Link relative="route" /> <Link relative="path" />
Consider a route hierarchy where a parent route pattern is "blog" and a child route pattern is "blog/:slug/edit".
- **route** — default, resolves the link relative to the route pattern. In the example above, a relative link of "..." will remove both :slug/edit segments back to "/blog". - **path** — relative to the path so "..." will only remove one URL segment up to "/blog/:slug"
Note that index routes and layout routes do not have paths so they are not included in the relative path calculation.

property reloadDocument

reloadDocument?: boolean;

Will use document navigation instead of client side routing when the link is clicked: the browser will handle the transition normally (as if it were an [<a href>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)).
<Link to="/logout" reloadDocument />

property replace

replace?: boolean;

Replaces the current entry in the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack instead of pushing a new one onto it.

<Link replace />

# with a history stack like this
A -> B

# normal link click pushes a new entry
A -> B -> C

# but with `replace`, B is replaced by C
A -> C

property state

state?: any;

Adds persistent client side routing state to the next location.
<Link to="/somewhere/else" state={{ some: "value" }} />
The location state is accessed from the location.
function SomeComp() { const location = useLocation(); location.state; // { some: "value" } }
This state is inaccessible on the server as it is implemented on top of [history.state](https://developer.mozilla.org/en-US/docs/Web/API/History/state)

property to

to: To;

Can be a string or a partial Path:

<Link to="/some/path" />

<Link
  to={{
    pathname: "/some/path",
    search: "?query=string",
    hash: "#hash",
  }}
/>

property unstable_defaultShouldRevalidate

unstable_defaultShouldRevalidate?: boolean;

Specify the default revalidation behavior for the navigation.
<Link to="/some/path" unstable_defaultShouldRevalidate={false} />
If no shouldRevalidate functions are present on the active routes, then this value will be used directly. Otherwise it will be passed into shouldRevalidate so the route can make the final determination on revalidation. This can be useful when updating search params and you don't want to trigger a revalidation.
By default (when not specified), loaders will revalidate according to the routers standard revalidation behavior.

property unstable_mask

unstable_mask?: To;

Masked path for for this navigation, when you want to navigate the router to one location but display a separate location in the URL bar.

This is useful for contextual navigations such as opening an image in a modal on top of a gallery while keeping the underlying gallery active. If a user shares the masked URL, or opens the link in a new tab, they will only load the masked location without the underlying contextual location.

This feature relies on history.state and is thus only intended for SPA uses and SSR renders will not respect the masking.

// routes/gallery.tsx
export function clientLoader({ request }: Route.LoaderArgs) {
  let sp = new URL(request.url).searchParams;
  return {
    images: getImages(),
    modalImage: sp.has("image") ? getImage(sp.get("image")!) : null,
  };
}

export default function Gallery({ loaderData }: Route.ComponentProps) {
  return (
    <>
      <GalleryGrid>
       {loaderData.images.map((image) => (
         <Link
           key={image.id}
           to={`/gallery?image=${image.id}`}
           unstable_mask={`/images/${image.id}`}
         >
           <img src={image.url} alt={image.alt} />
         </Link>
       ))}
      </GalleryGrid>

      {data.modalImage ? (
        <dialog open>
          <img src={data.modalImage.url} alt={data.modalImage.alt} />
        </dialog>
      ) : null}
    </>
  );
}

property viewTransition

viewTransition?: boolean;

Enables a [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) for this navigation.
<Link to={to} viewTransition> Click me </Link>
To apply specific styles for the transition, see useViewTransitionState

interface LinksFunction

interface LinksFunction {}

A function that defines <link> tags to be inserted into the <head> of the document on route transitions.
See Also
- https://reactrouter.com/start/framework/route-module#meta

call signature

(): LinkDescriptor[];

interface LinksProps

interface LinksProps {}

Props for the Links component.
Types

property crossOrigin

crossOrigin?: 'anonymous' | 'use-credentials';

A [crossOrigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) attribute to render on the [<link>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element

property nonce

nonce?: string | undefined;

A [nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce) attribute to render on the [<link>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element

interface LoaderFunctionArgs

interface LoaderFunctionArgs<Context = DefaultContext>
    extends DataFunctionArgs<Context> {}

Arguments passed to loader functions

interface Location

interface Location<State = any> extends Path {}

An entry in a history stack. A location contains information about the URL path, as well as possibly some arbitrary state and a key.

property key

key: string;

A unique string associated with this location. May be used to safely store and retrieve data in some other storage API, like localStorage.
Note: This value is always "default" on the initial location.

property state

state: State;

A value of arbitrary data associated with this location.

property unstable_mask

unstable_mask: Path | undefined;

The masked location displayed in the URL bar, which differs from the URL the router is operating on

interface MemoryRouterOpts

interface MemoryRouterOpts {}

Data Routers

property basename

basename?: string;

Basename path for the application.

property dataStrategy

dataStrategy?: DataStrategyFunction;

Override the default data strategy of running loaders in parallel - see the [docs](../../how-to/data-strategy) for more information.

let router = createBrowserRouter(routes, {
  async dataStrategy({
    matches,
    request,
    runClientMiddleware,
  }) {
    const matchesToLoad = matches.filter((m) =>
      m.shouldCallHandler(),
    );

    const results: Record<string, DataStrategyResult> = {};
    await runClientMiddleware(() =>
      Promise.all(
        matchesToLoad.map(async (match) => {
          results[match.route.id] = await match.resolve();
        }),
      ),
    );
    return results;
  },
});

property future

future?: Partial<FutureConfig>;

Future flags to enable for the router.

property getContext

getContext?: RouterInit['getContext'];

A function that returns an RouterContextProvider instance which is provided as the context argument to client [action](../../start/data/route-object#action)s, [loader](../../start/data/route-object#loader)s and [middleware](../../how-to/middleware). This function is called to generate a fresh context instance on each navigation or fetcher call.

property hydrationData

hydrationData?: HydrationState;

Hydration data to initialize the router with if you have already performed data loading on the server.

property initialEntries

initialEntries?: InitialEntry[];

Initial entries in the in-memory history stack

property initialIndex

initialIndex?: number;

Index of initialEntries the application should initialize to

property patchRoutesOnNavigation

patchRoutesOnNavigation?: PatchRoutesOnNavigationFunction;

Lazily define portions of the route tree on navigations.

property unstable_instrumentations

unstable_instrumentations?: unstable_ClientInstrumentation[];

let router = createBrowserRouter(routes, {
  unstable_instrumentations: [logging]
});


let logging = {
  router({ instrument }) {
    instrument({
      navigate: (impl, info) => logExecution(`navigate ${info.to}`, impl),
      fetch: (impl, info) => logExecution(`fetch ${info.to}`, impl)
    });
  },
  route({ instrument, id }) {
    instrument({
      middleware: (impl, info) => logExecution(
        `middleware ${info.request.url} (route ${id})`,
        impl
      ),
      loader: (impl, info) => logExecution(
        `loader ${info.request.url} (route ${id})`,
        impl
      ),
      action: (impl, info) => logExecution(
        `action ${info.request.url} (route ${id})`,
        impl
      ),
    })
  }
};

async function logExecution(label: string, impl: () => Promise<void>) {
  let start = performance.now();
  console.log(`start ${label}`);
  await impl();
  let duration = Math.round(performance.now() - start);
  console.log(`end ${label} (${duration}ms)`);
}

interface MemoryRouterProps

interface MemoryRouterProps {}

Types

property basename

basename?: string;

Application basename

property children

children?: React.ReactNode;

Nested Route elements describing the route tree

property initialEntries

initialEntries?: InitialEntry[];

Initial entries in the in-memory history stack

property initialIndex

initialIndex?: number;

Index of initialEntries the application should initialize to

property unstable_useTransitions

unstable_useTransitions?: boolean;

Control whether router state updates are internally wrapped in [React.startTransition](https://react.dev/reference/react/startTransition).
- When left undefined, all router state updates are wrapped in React.startTransition - When set to true, Link and Form navigations will be wrapped in React.startTransition and all router state updates are wrapped in React.startTransition - When set to false, the router will not leverage React.startTransition on any navigations or state changes.
For more information, please see the [docs](https://reactrouter.com/explanation/react-transitions).

interface MetaArgs

interface MetaArgs<
    Loader extends LoaderFunction | ClientLoaderFunction | unknown = unknown,
    MatchLoaders extends Record<
        string,
        LoaderFunction | ClientLoaderFunction | unknown
    > = Record<string, unknown>
> {}

property data

data:
    | (Loader extends LoaderFunction | ClientLoaderFunction
          ? SerializeFrom<Loader>
          : unknown)
    | undefined;

Deprecated
Use MetaArgs.loaderData instead

property error

error?: unknown;

property loaderData

loaderData:
    | (Loader extends LoaderFunction | ClientLoaderFunction
          ? SerializeFrom<Loader>
          : unknown)
    | undefined;

property location

location: Location;

property matches

matches: MetaMatches<MatchLoaders>;

property params

params: Params;

interface MetaFunction

interface MetaFunction<
    Loader extends LoaderFunction | ClientLoaderFunction | unknown = unknown,
    MatchLoaders extends Record<
        string,
        LoaderFunction | ClientLoaderFunction | unknown
    > = Record<string, unknown>
> {}

A function that returns an array of data objects to use for rendering metadata HTML tags in a route. These tags are not rendered on descendant routes in the route hierarchy. In other words, they will only be rendered on the route in which they are exported.

Parameter Loader

The type of the current route's loader function

Parameter MatchLoaders

Mapping from a parent route's filepath to its loader function type

Note that parent route filepaths are relative to the app/ directory.

For example, if this meta function is for /sales/customers/$customerId:

// app/root.tsx
const loader = () => ({ hello: "world" })
export type Loader = typeof loader

// app/routes/sales.tsx
const loader = () => ({ salesCount: 1074 })
export type Loader = typeof loader

// app/routes/sales/customers.tsx
const loader = () => ({ customerCount: 74 })
export type Loader = typeof loader

// app/routes/sales/customers/$customersId.tsx
import type { Loader as RootLoader } from "../../../root"
import type { Loader as SalesLoader } from "../../sales"
import type { Loader as CustomersLoader } from "../../sales/customers"

const loader = () => ({ name: "Customer name" })

const meta: MetaFunction<typeof loader, {
 "root": RootLoader,
 "routes/sales": SalesLoader,
 "routes/sales/customers": CustomersLoader,
}> = ({ data, matches }) => {
  const { name } = data
  //      ^? string
  const { customerCount } = matches.find((match) => match.id === "routes/sales/customers").data
  //      ^? number
  const { salesCount } = matches.find((match) => match.id === "routes/sales").data
  //      ^? number
  const { hello } = matches.find((match) => match.id === "root").data
  //      ^? "world"
}

call signature

(args: MetaArgs<Loader, MatchLoaders>): MetaDescriptor[] | undefined;

interface NavigateFunction

interface NavigateFunction {}

The interface for the navigate function returned from useNavigate.

call signature

(to: To, options?: NavigateOptions): void | Promise<void>;

call signature

(delta: number): void | Promise<void>;

interface NavigateOptions

interface NavigateOptions {}

property flushSync

flushSync?: boolean;

Wraps the initial state update for this navigation in a call instead of the default

property preventScrollReset

preventScrollReset?: boolean;

If you are using , prevent the scroll position from being reset to the top of the window when navigating

property relative

relative?: RelativeRoutingType;

Defines the relative path behavior for the link. "route" will use the route hierarchy so ".." will remove all URL segments of the current route pattern while "path" will use the URL path so ".." will remove one URL segment.

property replace

replace?: boolean;

Replace the current entry in the history stack instead of pushing a new one

property state

state?: any;

Adds persistent client side routing state to the next location

property unstable_defaultShouldRevalidate

unstable_defaultShouldRevalidate?: boolean;

Specifies the default revalidation behavior after this submission

property unstable_mask

unstable_mask?: To;

Masked URL

property viewTransition

viewTransition?: boolean;

Enables a for this navigation by wrapping the final state update in document.startViewTransition(). If you need to apply specific styles for this view transition, you will also need to leverage the hook.

interface NavigateProps

interface NavigateProps {}

Types

property relative

relative?: RelativeRoutingType;

How to interpret relative routing in the to prop. See RelativeRoutingType.

property replace

replace?: boolean;

Whether to replace the current entry in the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) stack

property state

state?: any;

State to pass to the new Location to store in [history.state](https://developer.mozilla.org/en-US/docs/Web/API/History/state).

property to

to: To;

The path to navigate to. This can be a string or a Path object

interface Navigator

interface Navigator {}

A Navigator is a "location changer"; it's how you get to different locations.
Every history instance conforms to the Navigator interface, but the distinction is useful primarily when it comes to the low-level <Router> API where both the location and a navigator must be provided separately in order to avoid "tearing" that may occur in a suspense-enabled app if the action and/or location were to be read directly from the history instance.

property createHref

createHref: History['createHref'];

property encodeLocation

encodeLocation?: History['encodeLocation'];

property go

go: History['go'];

method push

push: (to: To, state?: any, opts?: NavigateOptions) => void;

method replace

replace: (to: To, state?: any, opts?: NavigateOptions) => void;

interface NavLinkProps

interface NavLinkProps extends Omit<LinkProps, 'className' | 'style' | 'children'> {}

Types

property caseSensitive

caseSensitive?: boolean;

Changes the matching logic to make it case-sensitive:
| Link | URL | isActive | | -------------------------------------------- | ------------- | -------- | | <NavLink to="/SpOnGe-bOB" /> | /sponge-bob | true | | <NavLink to="/SpOnGe-bOB" caseSensitive /> | /sponge-bob | false |

property children

children?: React.ReactNode | ((props: NavLinkRenderProps) => React.ReactNode);

Can be regular React children or a function that receives an object with the active and pending states of the link.
```tsx {({ isActive }) => ( <span className={isActive ? "active" : ""}>Tasks )} ```

property className

className?: string | ((props: NavLinkRenderProps) => string | undefined);

Classes are automatically applied to NavLink that correspond to the state.

a.active {
  color: red;
}
a.pending {
  color: blue;
}
a.transitioning {
  view-transition-name: my-transition;
}

Or you can specify a function that receives NavLinkRenderProps and returns the className:

<NavLink className={({ isActive, isPending }) => (
  isActive ? "my-active-class" :
  isPending ? "my-pending-class" :
  ""
)} />

property end

end?: boolean;

Changes the matching logic for the active and pending states to only match to the "end" of the NavLinkProps.to. If the URL is longer, it will no longer be considered active.
| Link | URL | isActive | | ----------------------------- | ------------ | -------- | | <NavLink to="/tasks" /> | /tasks | true | | <NavLink to="/tasks" /> | /tasks/123 | true | | <NavLink to="/tasks" end /> | /tasks | true | | <NavLink to="/tasks" end /> | /tasks/123 | false |
<NavLink to="/"> is an exceptional case because _every_ URL matches /. To avoid this matching every single route by default, it effectively ignores the end prop and only matches when you're at the root route.

property style

style?:
    | React.CSSProperties
    | ((props: NavLinkRenderProps) => React.CSSProperties | undefined);

Styles can also be applied dynamically via a function that receives NavLinkRenderProps and returns the styles:

<NavLink to="/tasks" style={{ color: "red" }} />
<NavLink to="/tasks" style={({ isActive, isPending }) => ({
  color:
    isActive ? "red" :
    isPending ? "blue" : "black"
})} />

interface NonIndexRouteObject

interface NonIndexRouteObject {}

property action

action?: AgnosticNonIndexRouteObject['action'];

property caseSensitive

caseSensitive?: AgnosticNonIndexRouteObject['caseSensitive'];

property children

children?: RouteObject[];

property Component

Component?: React.ComponentType | null;

property element

element?: React.ReactNode | null;

property ErrorBoundary

ErrorBoundary?: React.ComponentType | null;

property errorElement

errorElement?: React.ReactNode | null;

property handle

handle?: AgnosticNonIndexRouteObject['handle'];

property hasErrorBoundary

hasErrorBoundary?: AgnosticNonIndexRouteObject['hasErrorBoundary'];

property HydrateFallback

HydrateFallback?: React.ComponentType | null;

property hydrateFallbackElement

hydrateFallbackElement?: React.ReactNode | null;

property id

id?: AgnosticNonIndexRouteObject['id'];

property index

index?: false;

property lazy

lazy?: LazyRouteDefinition<RouteObject>;

property loader

loader?: AgnosticNonIndexRouteObject['loader'];

property middleware

middleware?: AgnosticNonIndexRouteObject['middleware'];

property path

path?: AgnosticNonIndexRouteObject['path'];

property shouldRevalidate

shouldRevalidate?: AgnosticNonIndexRouteObject['shouldRevalidate'];

interface OutletProps

interface OutletProps {}

Types

property context

context?: unknown;

Provides a context value to the element tree below the outlet. Use when the parent route needs to provide values to child routes.
<Outlet context={myContextValue} />
Access the context with useOutletContext.

interface PageLinkDescriptor

interface PageLinkDescriptor
    extends Omit<
        HtmlLinkDescriptor,
        | 'href'
        | 'rel'
        | 'type'
        | 'sizes'
        | 'imageSrcSet'
        | 'imageSizes'
        | 'as'
        | 'color'
        | 'title'
    > {}

property nonce

nonce?: string | undefined;

A [nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce) attribute to render on the [<link>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element

property page

page: string;

The absolute path of the page to prefetch, e.g. /absolute/path.

interface Path

interface Path {}

The pathname, search, and hash values of a URL.

property hash

hash: string;

A URL fragment identifier, beginning with a #.

property pathname

pathname: string;

A URL pathname, beginning with a /.

property search

search: string;

A URL search string, beginning with a ?.

interface PathMatch

interface PathMatch<ParamKey extends string = string> {}

Contains info about how a PathPattern matched on a URL pathname.

property params

params: Params<ParamKey>;

The names and values of dynamic parameters in the URL.

property pathname

pathname: string;

The portion of the URL pathname that was matched.

property pathnameBase

pathnameBase: string;

The portion of the URL pathname that was matched before child routes.

property pattern

pattern: PathPattern;

The pattern that was used to match.

interface PathPattern

interface PathPattern<Path extends string = string> {}

Used to match on some portion of a URL pathname.

property caseSensitive

caseSensitive?: boolean;

Should be true if the static portions of the path should be matched in the same case.

property end

end?: boolean;

Should be true if this pattern should match the entire URL pathname.

property path

path: Path;

A string to match against a URL pathname. May contain :id-style segments to indicate placeholders for dynamic parameters. It May also end with /* to indicate matching the rest of the URL pathname.

interface PathRouteProps

interface PathRouteProps {}

Types

property action

action?: NonIndexRouteObject['action'];

The route action. See [action](../../start/data/route-object#action).

property caseSensitive

caseSensitive?: NonIndexRouteObject['caseSensitive'];

Whether the path should be case-sensitive. Defaults to false.

property children

children?: React.ReactNode;

Child Route components

property Component

Component?: React.ComponentType | null;

The React Component to render when this route matches. Mutually exclusive with element.

property element

element?: React.ReactNode | null;

The React element to render when this Route matches. Mutually exclusive with Component.

property ErrorBoundary

ErrorBoundary?: React.ComponentType | null;

The React Component to render at this route if an error occurs. Mutually exclusive with errorElement.

property errorElement

errorElement?: React.ReactNode | null;

The React element to render at this route if an error occurs. Mutually exclusive with ErrorBoundary.

property handle

handle?: NonIndexRouteObject['handle'];

The route handle.

property hasErrorBoundary

hasErrorBoundary?: NonIndexRouteObject['hasErrorBoundary'];

property HydrateFallback

HydrateFallback?: React.ComponentType | null;

The React Component to render while this router is loading data. Mutually exclusive with hydrateFallbackElement.

property hydrateFallbackElement

hydrateFallbackElement?: React.ReactNode | null;

The React element to render while this router is loading data. Mutually exclusive with HydrateFallback.

property id

id?: NonIndexRouteObject['id'];

The unique identifier for this route (for use with DataRouters)

property index

index?: false;

Whether this is an index route.

property lazy

lazy?: LazyRouteFunction<NonIndexRouteObject>;

A function that returns a promise that resolves to the route object. Used for code-splitting routes. See [lazy](../../start/data/route-object#lazy).

property loader

loader?: NonIndexRouteObject['loader'];

The route loader. See [loader](../../start/data/route-object#loader).

property middleware

middleware?: NonIndexRouteObject['middleware'];

The route middleware. See [middleware](../../start/data/route-object#middleware).

property path

path?: NonIndexRouteObject['path'];

The path pattern to match. If unspecified or empty, then this becomes a layout route.

property shouldRevalidate

shouldRevalidate?: NonIndexRouteObject['shouldRevalidate'];

The route shouldRevalidate function. See [shouldRevalidate](../../start/data/route-object#shouldRevalidate).

interface Register

interface Register {}

Apps can use this interface to "register" app-wide types for React Router via interface declaration merging and module augmentation. React Router should handle this for you via type generation.
For more on declaration merging and module augmentation, see https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation .

interface RouteMatch

interface RouteMatch<
    ParamKey extends string = string,
    RouteObjectType extends RouteObject = RouteObject
> extends AgnosticRouteMatch<ParamKey, RouteObjectType> {}

interface RouterContext

interface RouterContext<T = unknown> {}

A context instance used as the key for the get/set methods of a RouterContextProvider. Accepts an optional default value to be returned if no value has been set.

property defaultValue

defaultValue?: T;

interface RouterInit

interface RouterInit {}

Initialization options for createRouter

property basename

basename?: string;

property dataStrategy

dataStrategy?: DataStrategyFunction;

property future

future?: Partial<FutureConfig>;

property getContext

getContext?: () => MaybePromise<RouterContextProvider>;

property history

history: History;

property hydrationData

hydrationData?: HydrationState;

property hydrationRouteProperties

hydrationRouteProperties?: string[];

property mapRouteProperties

mapRouteProperties?: MapRoutePropertiesFunction;

property patchRoutesOnNavigation

patchRoutesOnNavigation?: AgnosticPatchRoutesOnNavigationFunction;

property routes

routes: AgnosticRouteObject[];

property unstable_instrumentations

unstable_instrumentations?: unstable_ClientInstrumentation[];

property window

window?: Window;

interface RouterProps

interface RouterProps {}

Types

property basename

basename?: string;

The base path for the application. This is prepended to all locations

property children

children?: React.ReactNode;

Nested Route elements describing the route tree

property location

location: Partial<Location> | string;

The location to match against. Defaults to the current location. This can be a string or a Location object.

property navigationType

navigationType?: Action;

The type of navigation that triggered this location change. Defaults to NavigationType.Pop.

property navigator

navigator: Navigator;

The navigator to use for navigation. This is usually a history object or a custom navigator that implements the Navigator interface.

property static

static?: boolean;

Whether this router is static or not (used for SSR). If true, the router will not be reactive to location changes.

property unstable_useTransitions

unstable_useTransitions?: boolean;

Control whether router state updates are internally wrapped in [React.startTransition](https://react.dev/reference/react/startTransition).
- When left undefined, all router state updates are wrapped in React.startTransition - When set to true, Link and Form navigations will be wrapped in React.startTransition and all router state updates are wrapped in React.startTransition - When set to false, the router will not leverage React.startTransition on any navigations or state changes.
For more information, please see the [docs](https://reactrouter.com/explanation/react-transitions).

interface RouterProviderProps

interface RouterProviderProps {}

Types

property flushSync

flushSync?: (fn: () => unknown) => undefined;

The [ReactDOM.flushSync](https://react.dev/reference/react-dom/flushSync) implementation to use for flushing updates.
You usually don't have to worry about this: - The RouterProvider exported from react-router/dom handles this internally for you - If you are rendering in a non-DOM environment, you can import RouterProvider from react-router and ignore this prop

property onError

onError?: ClientOnErrorFunction;

An error handler function that will be called for any middleware, loader, action, or render errors that are encountered in your application. This is useful for logging or reporting errors instead of in the ErrorBoundary because it's not subject to re-rendering and will only run one time per error.
The errorInfo parameter is passed along from [componentDidCatch](https://react.dev/reference/react/Component#componentdidcatch) and is only present for render errors.
<RouterProvider onError=(error, info) => { let { location, params, unstable_pattern, errorInfo } = info; console.error(error, location, errorInfo); reportToErrorService(error, location, errorInfo); }} />

property router

router: Router$1;

The DataRouter instance to use for navigation and data fetching.

property unstable_useTransitions

unstable_useTransitions?: boolean;

Control whether router state updates are internally wrapped in [React.startTransition](https://react.dev/reference/react/startTransition).
- When left undefined, all state updates are wrapped in React.startTransition - This can lead to buggy behaviors if you are wrapping your own navigations/fetchers in startTransition. - When set to true, Link and Form navigations will be wrapped in React.startTransition and router state changes will be wrapped in React.startTransition and also sent through [useOptimistic](https://react.dev/reference/react/useOptimistic) to surface mid-navigation router state changes to the UI. - When set to false, the router will not leverage React.startTransition or React.useOptimistic on any navigations or state changes.
For more information, please see the [docs](https://reactrouter.com/explanation/react-transitions).

interface RouterState

interface RouterState {}

State maintained internally by the router. During a navigation, all states reflect the "old" location unless otherwise noted.

property actionData

actionData: RouteData | null;

Data from the action for the current matches

property blockers

blockers: Map<string, Blocker>;

Map of current blockers

property errors

errors: RouteData | null;

Errors caught from loaders for the current matches

property fetchers

fetchers: Map<string, Fetcher>;

Map of current fetchers

property historyAction

historyAction: Action;

The action of the most recent navigation

property initialized

initialized: boolean;

Tracks whether we've completed our initial data load

property loaderData

loaderData: RouteData;

Data from the loaders for the current matches

property location

location: Location;

The current location reflected by the router

property matches

matches: AgnosticDataRouteMatch[];

The current set of route matches

navigation: Navigation;

Tracks the state of the current navigation

property preventScrollReset

preventScrollReset: boolean;

Indicate whether this navigation should skip resetting the scroll position if we are unable to restore the scroll position

property renderFallback

renderFallback: boolean;

Tracks whether we should be rendering a HydrateFallback during hydration

property restoreScrollPosition

restoreScrollPosition: number | false | null;

Current scroll position we should start at for a new view - number -> scroll position to restore to - false -> do not restore scroll at all (used during submissions/revalidations) - null -> don't have a saved position, scroll to hash or top of page

property revalidation

revalidation: RevalidationState;

Tracks any in-progress revalidations

interface RouterSubscriber

interface RouterSubscriber {}

Subscriber function signature for changes to router state

call signature

(
    state: RouterState,
    opts: {
        deletedFetchers: string[];
        newErrors: RouteData | null;
        viewTransitionOpts?: ViewTransitionOpts;
        flushSync: boolean;
    }
): void;

interface RoutesProps

interface RoutesProps {}

Types

property children

children?: React.ReactNode;

Nested Route elements

property location

location?: Partial<Location> | string;

The Location to match against. Defaults to the current location.

interface RoutesTestStubProps

interface RoutesTestStubProps {}

property future

future?: Partial<FutureConfig>;

Future flags mimicking the settings in react-router.config.ts

property hydrationData

hydrationData?: HydrationState;

Used to set the route's initial loader and action data. e.g. hydrationData={{ loaderData: { "/contact": { locale: "en-US" } }, actionData: { "/login": { errors: { email: "invalid email" } }} }}

property initialEntries

initialEntries?: InitialEntry[];

The initial entries in the history stack. This allows you to start a test with multiple locations already in the history stack (for testing a back navigation, etc.) The test will default to the last entry in initialEntries if no initialIndex is provided. e.g. initialEntries={["/home", "/about", "/contact"]}

property initialIndex

initialIndex?: number;

The initial index in the history stack to render. This allows you to start a test at a specific entry. It defaults to the last entry in initialEntries. e.g. initialEntries: ["/", "/events/123"] initialIndex: 1 // start at "/events/123"

interface ServerBuild

interface ServerBuild {}

The output of the compiler for the server build.

property allowedActionOrigins

allowedActionOrigins?: string[] | false;

property assets

assets: AssetsManifest;

property assetsBuildDirectory

assetsBuildDirectory: string;

property basename

basename?: string;

property entry

entry: {
    module: ServerEntryModule;
};

property future

future: FutureConfig;

property isSpaMode

isSpaMode: boolean;

Deprecated
This is now done via a custom header during prerendering

property prerender

prerender: string[];

property publicPath

publicPath: string;

property routeDiscovery

routeDiscovery: {
    mode: 'lazy' | 'initial';
    manifestPath: string;
};

property routes

routes: ServerRouteManifest;

property ssr

ssr: boolean;

property unstable_getCriticalCss

unstable_getCriticalCss?: (args: {
    pathname: string;
}) => OptionalCriticalCss | Promise<OptionalCriticalCss>;

interface ServerEntryModule

interface ServerEntryModule {}

A module that serves as the entry point for a Remix app during server rendering.

property default

default: HandleDocumentRequestFunction;

property handleDataRequest

handleDataRequest?: HandleDataRequestFunction;

property handleError

handleError?: HandleErrorFunction;

property streamTimeout

streamTimeout?: number;

property unstable_instrumentations

unstable_instrumentations?: unstable_ServerInstrumentation[];

interface ServerRouterProps

interface ServerRouterProps {}

Types

property context

context: EntryContext;

The entry context containing the manifest, route modules, and other data needed for rendering.

property nonce

nonce?: string;

An optional nonce for [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) compliance, used to allow inline scripts to run safely.

property url

url: string | URL;

The URL of the request being handled.

interface Session

interface Session<Data = SessionData, FlashData = Data> {}

Session persists data across HTTP requests.
See Also
- https://reactrouter.com/explanation/sessions-and-cookies#sessions

property data

readonly data: FlashSessionData<Data, FlashData>;

The raw data contained in this session.
This is useful mostly for SessionStorage internally to access the raw session data to persist.

property id

readonly id: string;

A unique identifier for this session.
Note: This will be the empty string for newly created sessions and sessions that are not backed by a database (i.e. cookie-based sessions).

method flash

flash: <Key extends keyof FlashData & string>(
    name: Key,
    value: FlashData[Key]
) => void;

Sets a value in the session that is only valid until the next get(). This can be useful for temporary values, like error messages.

method get

get: <Key extends (keyof FlashData | keyof Data) & string>(
    name: Key
) =>
    | (Key extends keyof Data ? Data[Key] : undefined)
    | (Key extends keyof FlashData ? FlashData[Key] : undefined)
    | undefined;

Returns the value for the given name in this session.

method has

has: (name: (keyof Data | keyof FlashData) & string) => boolean;

Returns true if the session has a value for the given name, false otherwise.

method set

set: <Key extends keyof Data & string>(name: Key, value: Data[Key]) => void;

Sets a value in the session for the given name.

method unset

unset: (name: keyof Data & string) => void;

Removes a value from the session.

interface SessionData

interface SessionData {}

An object of name/value pairs to be used in the session.

index signature

[name: string]: any;

interface SessionIdStorageStrategy

interface SessionIdStorageStrategy<Data = SessionData, FlashData = Data> {}

SessionIdStorageStrategy is designed to allow anyone to easily build their own SessionStorage using createSessionStorage(strategy).
This strategy describes a common scenario where the session id is stored in a cookie but the actual session data is stored elsewhere, usually in a database or on disk. A set of create, read, update, and delete operations are provided for managing the session data.

cookie?:
    | Cookie
    | (CookieOptions & {
          name?: string;
      });

The Cookie used to store the session id, or options used to automatically create one.

property createData

createData: (
    data: FlashSessionData<Data, FlashData>,
    expires?: Date
) => Promise<string>;

Creates a new record with the given data and returns the session id.

property deleteData

deleteData: (id: string) => Promise<void>;

Deletes data for a given session id from the data store.

property readData

readData: (id: string) => Promise<FlashSessionData<Data, FlashData> | null>;

Returns data for a given session id, or null if there isn't any.

property updateData

updateData: (
    id: string,
    data: FlashSessionData<Data, FlashData>,
    expires?: Date
) => Promise<void>;

Updates data for the given session id.

interface SessionStorage

interface SessionStorage<Data = SessionData, FlashData = Data> {}

SessionStorage stores session data between HTTP requests and knows how to parse and create cookies.
A SessionStorage creates Session objects using a Cookie header as input. Then, later it generates the Set-Cookie header to be used in the response.

property commitSession

commitSession: (
    session: Session<Data, FlashData>,
    options?: SerializeOptions
) => Promise<string>;

Stores all data in the Session and returns the Set-Cookie header to be used in the HTTP response.

property destroySession

destroySession: (
    session: Session<Data, FlashData>,
    options?: SerializeOptions
) => Promise<string>;

Deletes all data associated with the Session and returns the Set-Cookie header to be used in the HTTP response.

property getSession

getSession: (
    cookieHeader?: string | null,
    options?: ParseOptions
) => Promise<Session<Data, FlashData>>;

Parses a Cookie header from a HTTP request and returns the associated Session. If there is no session associated with the cookie, this will return a new Session with no data.

interface ShouldRevalidateFunction

interface ShouldRevalidateFunction {}

Route shouldRevalidate function signature. This runs after any submission (navigation or fetcher), so we flatten the navigation/fetcher submission onto the arguments. It shouldn't matter whether it came from a navigation or a fetcher, what really matters is the URLs and the formData since loaders have to re-run based on the data models that were potentially mutated.

call signature

(args: ShouldRevalidateFunctionArgs): boolean;

interface ShouldRevalidateFunctionArgs

interface ShouldRevalidateFunctionArgs {}

Arguments passed to shouldRevalidate function

property actionResult

actionResult?: any;

When a submission causes the revalidation this will be the result of the action—either action data or an error if the action failed. It's common to include some information in the action result to instruct shouldRevalidate to revalidate or not.
Example 1
export async function action() { await saveSomeStuff(); return { ok: true }; }
export function shouldRevalidate({ actionResult, }) { if (actionResult?.ok) { return false; } return true; }

property actionStatus

actionStatus?: number;

The status code of the action response

property currentParams

currentParams: AgnosticDataRouteMatch['params'];

These are the from the URL that can be compared to the nextParams to decide if you need to reload or not. Perhaps you're using only a partial piece of the param for data loading, you don't need to revalidate if a superfluous part of the param changed.

property currentUrl

currentUrl: URL;

This is the url the navigation started from. You can compare it with nextUrl to decide if you need to revalidate this route's data.

property defaultShouldRevalidate

defaultShouldRevalidate: boolean;

By default, React Router doesn't call every loader all the time. There are reliable optimizations it can make by default. For example, only loaders with changing params are called. Consider navigating from the following URL to the one below it:
/projects/123/tasks/abc /projects/123/tasks/def React Router will only call the loader for tasks/def because the param for projects/123 didn't change.
It's safest to always return defaultShouldRevalidate after you've done your specific optimizations that return false, otherwise your UI might get out of sync with your data on the server.

property formAction

formAction?: Submission['formAction'];

The form action (<Form action="/somewhere">) that triggered the revalidation.

property formData

formData?: Submission['formData'];

The form submission data when the form's encType is application/x-www-form-urlencoded or multipart/form-data

property formEncType

formEncType?: Submission['formEncType'];

The form encType (`) used in the form submission that triggered the revalidation

property formMethod

formMethod?: Submission['formMethod'];

The method (probably "GET" or "POST") used in the form submission that triggered the revalidation.

property json

json?: Submission['json'];

The form submission data when the form's encType is application/json

property nextParams

nextParams: AgnosticDataRouteMatch['params'];

In the case of navigation, these are the from the next location the user is requesting. Some revalidations are not navigation, so it will simply be the same as currentParams.

property nextUrl

nextUrl: URL;

In the case of navigation, this the URL the user is requesting. Some revalidations are not navigation, so it will simply be the same as currentUrl.

property text

text?: Submission['text'];

The form submission data when the form's encType is text/plain

interface StaticHandler

interface StaticHandler {}

A StaticHandler instance manages a singular SSR navigation/fetch event

property dataRoutes

dataRoutes: AgnosticDataRouteObject[];

method query

query: (
    request: Request,
    opts?: {
        requestContext?: unknown;
        filterMatchesToLoad?: (match: AgnosticDataRouteMatch) => boolean;
        skipLoaderErrorBubbling?: boolean;
        skipRevalidation?: boolean;
        dataStrategy?: DataStrategyFunction<unknown>;
        generateMiddlewareResponse?: (
            query: (
                r: Request,
                args?: {
                    filterMatchesToLoad?: (
                        match: AgnosticDataRouteMatch
                    ) => boolean;
                }
            ) => Promise<StaticHandlerContext | Response>
        ) => MaybePromise<Response>;
    }
) => Promise<StaticHandlerContext | Response>;

method queryRoute

queryRoute: (
    request: Request,
    opts?: {
        routeId?: string;
        requestContext?: unknown;
        dataStrategy?: DataStrategyFunction<unknown>;
        generateMiddlewareResponse?: (
            queryRoute: (r: Request) => Promise<Response>
        ) => MaybePromise<Response>;
    }
) => Promise<any>;

interface StaticHandlerContext

interface StaticHandlerContext {}

State returned from a server-side query() call

property actionData

actionData: RouterState['actionData'];

property actionHeaders

actionHeaders: Record<string, Headers>;

property basename

basename: Router$1['basename'];

property errors

errors: RouterState['errors'];

property loaderData

loaderData: RouterState['loaderData'];

property loaderHeaders

loaderHeaders: Record<string, Headers>;

property location

location: RouterState['location'];

property matches

matches: RouterState['matches'];

property statusCode

statusCode: number;

interface StaticRouterProps

interface StaticRouterProps {}

Types

property basename

basename?: string;

The base URL for the static router (default: /)

property children

children?: React.ReactNode;

The child elements to render inside the static router

property location

location: Partial<Location> | string;

The Location to render the static router at (default: /)

interface StaticRouterProviderProps

interface StaticRouterProviderProps {}

Types

property context

context: StaticHandlerContext;

The StaticHandlerContext returned from StaticHandler's query

property hydrate

hydrate?: boolean;

Whether to hydrate the router on the client (default true)

property nonce

nonce?: string;

The [nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce) to use for the hydration [<script>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) tag

property router

router: Router;

The static DataRouter from createStaticRouter

interface SubmitFunction

interface SubmitFunction {}

Submits a HTML [<form>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) to the server without reloading the page.

call signature

(
    /**
     * Can be multiple types of elements and objects
     *
     * **[`HTMLFormElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement)**
     *
     * ```tsx
     * <Form
     *   onSubmit={(event) => {
     *     submit(event.currentTarget);
     *   }}
     * />
     * ```
     *
     * **[`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)**
     *
     * ```tsx
     * const formData = new FormData();
     * formData.append("myKey", "myValue");
     * submit(formData, { method: "post" });
     * ```
     *
     * **Plain object that will be serialized as [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)**
     *
     * ```tsx
     * submit({ myKey: "myValue" }, { method: "post" });
     * ```
     *
     * **Plain object that will be serialized as JSON**
     *
     * ```tsx
     * submit(
     *   { myKey: "myValue" },
     *   { method: "post", encType: "application/json" }
     * );
     * ```
     */
    target: SubmitTarget,
    /**
     * Options that override the [`<form>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form)'s
     * own attributes. Required when submitting arbitrary data without a backing
     * [`<form>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form).
     */
    options?: SubmitOptions
): Promise<void>;

interface SubmitOptions

interface SubmitOptions extends FetcherSubmitOptions {}

Submit options available to navigations

property fetcherKey

fetcherKey?: string;

Indicate a specific fetcherKey to use when using navigate=false

property navigate

navigate?: boolean;

navigate=false will use a fetcher instead of a navigation

property replace

replace?: boolean;

Set true to replace the current entry in the browser's history stack instead of creating a new one (i.e. stay on "the same page"). Defaults to false.

property state

state?: any;

State object to add to the history stack entry for this navigation

property viewTransition

viewTransition?: boolean;

Enable view transitions on this submission navigation

interface UIMatch

interface UIMatch<Data = unknown, Handle = unknown> {}

property data

data: Data | undefined;

The return value from the matched route's loader or clientLoader. This might be undefined if this route's loader (or a deeper route's loader) threw an error and we're currently displaying an ErrorBoundary.
Deprecated
Use UIMatch.loaderData instead

property handle

handle: Handle;

The exported from the matched route module

property id

id: string;

property loaderData

loaderData: Data | undefined;

The return value from the matched route's loader or clientLoader. This might be undefined if this route's loader (or a deeper route's loader) threw an error and we're currently displaying an ErrorBoundary.

property params

params: AgnosticRouteMatch['params'];

for the matched route.

property pathname

pathname: string;

interface UNSAFE_AssetsManifest

interface AssetsManifest {}

property entry

entry: {
    imports: string[];
    module: string;
};

property hmr

hmr?: {
    timestamp?: number;
    runtime: string;
};

property routes

routes: RouteManifest<EntryRoute>;

property sri

sri?: Record<string, string> | true;

property url

url: string;

property version

version: string;

interface UNSAFE_RouteModules

interface RouteModules {}

index signature

[routeId: string]: RouteModule | undefined;

interface unstable_RSCHydratedRouterProps

interface RSCHydratedRouterProps {}

Props for the unstable_RSCHydratedRouter component.
unstable_RSCHydratedRouterProps Types

property createFromReadableStream

createFromReadableStream: BrowserCreateFromReadableStreamFunction;

Your react-server-dom-xyz/client's createFromReadableStream function, used to decode payloads from the server.

property fetch

fetch?: (request: Request) => Promise<Response>;

Optional fetch implementation. Defaults to global [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch).

property getContext

getContext?: RouterInit['getContext'];

A function that returns an RouterContextProvider instance which is provided as the context argument to client [action](../../start/data/route-object#action)s, [loader](../../start/data/route-object#loader)s and [middleware](../../how-to/middleware). This function is called to generate a fresh context instance on each navigation or fetcher call.

property payload

payload: RSCPayload;

The decoded unstable_RSCPayload to hydrate.

property routeDiscovery

routeDiscovery?: 'eager' | 'lazy';

"eager" or "lazy" - Determines if links are eagerly discovered, or delayed until clicked.

interface unstable_RSCStaticRouterProps

interface RSCStaticRouterProps {}

Props for the unstable_RSCStaticRouter component.
unstable_RSCStaticRouterProps Types

property getPayload

getPayload: () => DecodedPayload;

A function that starts decoding of the unstable_RSCPayload. Usually passed through from unstable_routeRSCServerRequest's renderHTML.

Enums

enum NavigationType

enum NavigationType {
    Pop = 'POP',
    Push = 'PUSH',
    Replace = 'REPLACE',
}

Actions represent the type of change to a location value.

member Pop

Pop = 'POP'

A POP indicates a change to an arbitrary index in the history stack, such as a back or forward navigation. It does not describe the direction of the navigation, only that the current index changed.
Note: This is the default action for newly created history objects.

member Push

Push = 'PUSH'

A PUSH indicates a new entry being added to the history stack, such as when a link is clicked and a new page loads. When this happens, all subsequent entries in the stack are lost.

member Replace

Replace = 'REPLACE'

A REPLACE indicates the entry at the current index in the history stack being replaced by a new one.

enum UNSAFE_ServerMode

enum UNSAFE_ServerMode {
    Development = 'development',
    Production = 'production',
    Test = 'test',
}

The mode to use when running the server.

member Development

Development = 'development'

member Production

Production = 'production'

member Test

Test = 'test'

Type Aliases

type Blocker

type Blocker = BlockerUnblocked | BlockerBlocked | BlockerProceeding;

type BlockerFunction

type BlockerFunction = (args: {
    currentLocation: Location;
    nextLocation: Location;
    historyAction: Action;
}) => boolean;

type ClientActionFunction

type ClientActionFunction = (
    args: ClientActionFunctionArgs
) => ReturnType<ActionFunction>;

A function that handles data mutations for a route on the client

type ClientActionFunctionArgs

type ClientActionFunctionArgs = ActionFunctionArgs & {
    serverAction: <T = unknown>() => Promise<SerializeFrom<T>>;
};

Arguments passed to a route clientAction function

type ClientLoaderFunction

type ClientLoaderFunction = ((
    args: ClientLoaderFunctionArgs
) => ReturnType<LoaderFunction>) & {
    hydrate?: boolean;
};

A function that loads data for a route on the client

type ClientLoaderFunctionArgs

type ClientLoaderFunctionArgs = LoaderFunctionArgs & {
    serverLoader: <T = unknown>() => Promise<SerializeFrom<T>>;
};

Arguments passed to a route clientLoader function

type CookieOptions

type CookieOptions = ParseOptions & SerializeOptions & CookieSignatureOptions;

type CreateRequestHandlerFunction

type CreateRequestHandlerFunction = (
    build: ServerBuild | (() => ServerBuild | Promise<ServerBuild>),
    mode?: string
) => RequestHandler;

type DataRouteObject

type DataRouteObject = RouteObject & {
    children?: DataRouteObject[];
    id: string;
};

type DiscoverBehavior

type DiscoverBehavior = 'render' | 'none';

Defines the [lazy route discovery](../../explanation/lazy-route-discovery) behavior of the link/form:
- "render" - default, discover the route when the link renders - "none" - don't eagerly discover, only discover if the link is clicked

type ErrorResponse

type ErrorResponse = {
    status: number;
    statusText: string;
    data: any;
};

type Fetcher

type Fetcher<TData = any> = FetcherStates<TData>[keyof FetcherStates<TData>];

type FetcherWithComponents

type FetcherWithComponents<TData> = Fetcher<TData> & {
    /**
     * Just like {@link Form} except it doesn't cause a navigation.
     *
     * ```tsx
     * function SomeComponent() {
     *   const fetcher = useFetcher()
     *   return (
     *     <fetcher.Form method="post" action="/some/route">
     *       <input type="text" />
     *     </fetcher.Form>
     *   )
     * }
     * ```
     */
    Form: React.ForwardRefExoticComponent<
        FetcherFormProps & React.RefAttributes<HTMLFormElement>
    >;
    /**
     * Loads data from a route. Useful for loading data imperatively inside user
     * events outside a normal button or form, like a combobox or search input.
     *
     * ```tsx
     * let fetcher = useFetcher()
     *
     * <input onChange={e => {
     *   fetcher.load(`/search?q=${e.target.value}`)
     * }} />
     * ```
     */
    load: (
        href: string,
        opts?: {
            /**
             * Wraps the initial state update for this `fetcher.load` in a
             * [`ReactDOM.flushSync`](https://react.dev/reference/react-dom/flushSync)
             * call instead of the default [`React.startTransition`](https://react.dev/reference/react/startTransition).
             * This allows you to perform synchronous DOM actions immediately after the
             * update is flushed to the DOM.
             */
            flushSync?: boolean;
        }
    ) => Promise<void>;
    /**
     * Reset a fetcher back to an empty/idle state.
     *
     * If the fetcher is currently in-flight, the
     * [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController)
     * will be aborted with the `reason`, if provided.
     *
     * @param reason Optional `reason` to provide to [`AbortController.abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort)
     * @returns void
     */
    reset: (opts?: { reason?: unknown }) => void;
    /**
     *  Submits form data to a route. While multiple nested routes can match a URL, only the leaf route will be called.
     *
     *  The `formData` can be multiple types:
     *
     *  - [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
     *    A `FormData` instance.
     *  - [`HTMLFormElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement)
     *    A [`<form>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) DOM element.
     *  - `Object`
     *    An object of key/value-pairs that will be converted to a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
     *    instance by default. You can pass a more complex object and serialize it
     *    as JSON by specifying `encType: "application/json"`. See
     *    {@link useSubmit} for more details.
     *
     *  If the method is `GET`, then the route [`loader`](../../start/framework/route-module#loader)
     *  is being called and with the `formData` serialized to the url as [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams).
     *  If `DELETE`, `PATCH`, `POST`, or `PUT`, then the route [`action`](../../start/framework/route-module#action)
     *  is being called with `formData` as the body.
     *
     *  ```tsx
     *  // Submit a FormData instance (GET request)
     *  const formData = new FormData();
     *  fetcher.submit(formData);
     *
     *  // Submit the HTML form element
     *  fetcher.submit(event.currentTarget.form, {
     *    method: "POST",
     *  });
     *
     *  // Submit key/value JSON as a FormData instance
     *  fetcher.submit(
     *    { serialized: "values" },
     *    { method: "POST" }
     *  );
     *
     *  // Submit raw JSON
     *  fetcher.submit(
     *    {
     *      deeply: {
     *        nested: {
     *          json: "values",
     *        },
     *      },
     *    },
     *    {
     *      method: "POST",
     *      encType: "application/json",
     *    }
     *  );
     *  ```
     */
    submit: FetcherSubmitFunction;
};

The return value useFetcher that keeps track of the state of a fetcher.
let fetcher = useFetcher();

type FlashSessionData

type FlashSessionData<Data, FlashData> = Partial<
    Data & {
        [Key in keyof FlashData as FlashDataKey<Key & string>]: FlashData[Key];
    }
>;

type FormEncType

type FormEncType =
    | 'application/x-www-form-urlencoded'
    | 'multipart/form-data'
    | 'application/json'
    | 'text/plain';

type FormMethod

type FormMethod = UpperCaseFormMethod;

Active navigation/fetcher form methods are exposed in uppercase on the RouterState. This is to align with the normalization done via fetch().

type HeadersArgs

type HeadersArgs = {
    loaderHeaders: Headers;
    parentHeaders: Headers;
    actionHeaders: Headers;
    errorHeaders: Headers | undefined;
};

type HTMLFormMethod

type HTMLFormMethod = LowerCaseFormMethod | UpperCaseFormMethod;

Users can specify either lowercase or uppercase form methods on <Form>, useSubmit(), <fetcher.Form>, etc.

type HtmlLinkDescriptor

type HtmlLinkDescriptor =
    | (HtmlLinkProps & Pick<Required<HtmlLinkProps>, 'href'>)
    | (HtmlLinkPreloadImage & Pick<Required<HtmlLinkPreloadImage>, 'imageSizes'>)
    | (HtmlLinkPreloadImage &
          Pick<Required<HtmlLinkPreloadImage>, 'href'> & {
              imageSizes?: never;
          });

Represents a <link> element.
WHATWG Specification: https://html.spec.whatwg.org/multipage/semantics.html#the-link-element

type HydrationState

type HydrationState = Partial<
    Pick<RouterState, 'loaderData' | 'actionData' | 'errors'>
>;

Data that can be passed into hydrate a Router from SSR

type InitialEntry

type InitialEntry = string | Partial<Location>;

A user-supplied object that describes a location. Used when providing entries to createMemoryHistory via its initialEntries option.

type IsCookieFunction

type IsCookieFunction = (object: any) => object is Cookie;

type IsSessionFunction

type IsSessionFunction = (object: any) => object is Session;

type LinkDescriptor

type LinkDescriptor = HtmlLinkDescriptor | PageLinkDescriptor;

type LoaderFunction

type LoaderFunction<Context = DefaultContext> = {
    (
        args: LoaderFunctionArgs<Context>,
        handlerCtx?: unknown
    ): DataFunctionReturnValue;
} & {
    hydrate?: boolean;
};

Route loader function signature

type MetaDescriptor

type MetaDescriptor =
    | {
          charSet: 'utf-8';
      }
    | {
          title: string;
      }
    | {
          name: string;
          content: string;
      }
    | {
          property: string;
          content: string;
      }
    | {
          httpEquiv: string;
          content: string;
      }
    | {
          'script:ld+json': LdJsonObject;
      }
    | {
          tagName: 'meta' | 'link';
          [name: string]: string;
      }
    | {
          [name: string]: unknown;
      };

type MiddlewareFunction

type MiddlewareFunction<Result = unknown> = (
    args: DataFunctionArgs<Readonly<RouterContextProvider>>,
    next: MiddlewareNextFunction<Result>
) => MaybePromise<Result | void>;

Route middleware function signature. Receives the same "data" arguments as a loader/action (request, params, context) as the first parameter and a next function as the second parameter which will call downstream handlers and then complete middlewares from the bottom-up

type Navigation = NavigationStates[keyof NavigationStates];

type NavigationStates

type NavigationStates = {
    Idle: {
        state: 'idle';
        location: undefined;
        formMethod: undefined;
        formAction: undefined;
        formEncType: undefined;
        formData: undefined;
        json: undefined;
        text: undefined;
    };
    Loading: {
        state: 'loading';
        location: Location;
        formMethod: Submission['formMethod'] | undefined;
        formAction: Submission['formAction'] | undefined;
        formEncType: Submission['formEncType'] | undefined;
        formData: Submission['formData'] | undefined;
        json: Submission['json'] | undefined;
        text: Submission['text'] | undefined;
    };
    Submitting: {
        state: 'submitting';
        location: Location;
        formMethod: Submission['formMethod'];
        formAction: Submission['formAction'];
        formEncType: Submission['formEncType'];
        formData: Submission['formData'];
        json: Submission['json'];
        text: Submission['text'];
    };
};

Potential states for state.navigation

type NavLinkRenderProps

type NavLinkRenderProps = {
    /**
     * Indicates if the link's URL matches the current {@link Location}.
     */
    isActive: boolean;
    /**
     * Indicates if the pending {@link Location} matches the link's URL. Only
     * available in Framework/Data modes.
     */
    isPending: boolean;
    /**
     * Indicates if a view transition to the link's URL is in progress.
     * See {@link useViewTransitionState}
     */
    isTransitioning: boolean;
};

The object passed to NavLink children, className, and style prop callbacks to render and style the link based on its state.

// className
<NavLink
  to="/messages"
  className={({ isActive, isPending }) =>
    isPending ? "pending" : isActive ? "active" : ""
  }
>
  Messages
</NavLink>

// style
<NavLink
  to="/messages"
  style={({ isActive, isPending }) => {
    return {
      fontWeight: isActive ? "bold" : "",
      color: isPending ? "red" : "black",
    }
  )}
/>

// children
<NavLink to="/tasks">
  {({ isActive, isPending }) => (
    <span className={isActive ? "active" : ""}>Tasks</span>
  )}
</NavLink>

type ParamKeyValuePair

type ParamKeyValuePair = [string, string];

type ParamParseKey

type ParamParseKey<Segment extends string> = [PathParam<Segment>] extends [never]
    ? string
    : PathParam<Segment>;

type Params

type Params<Key extends string = string> = {
    readonly [key in Key]: string | undefined;
};

The parameters that were parsed from the URL path.

type PatchRoutesOnNavigationFunction

type PatchRoutesOnNavigationFunction = AgnosticPatchRoutesOnNavigationFunction<
    RouteObject,
    RouteMatch
>;

type PatchRoutesOnNavigationFunctionArgs

type PatchRoutesOnNavigationFunctionArgs =
    AgnosticPatchRoutesOnNavigationFunctionArgs<RouteObject, RouteMatch>;

type PathParam

type PathParam<Path extends string> = Path extends '*' | '/*'
    ? '*'
    : Path extends `${infer Rest}/*`
    ? '*' | _PathParam<Rest>
    : _PathParam<Path>;

type PrefetchBehavior

type PrefetchBehavior = 'intent' | 'render' | 'none' | 'viewport';

Defines the prefetching behavior of the link:
- "none": Never fetched - "intent": Fetched when the user focuses or hovers the link - "render": Fetched when the link is rendered - "viewport": Fetched when the link is in the viewport

type RedirectFunction

type RedirectFunction = (url: string, init?: number | ResponseInit) => Response;

type RelativeRoutingType

type RelativeRoutingType = 'route' | 'path';

- "route": relative to the route hierarchy so .. means remove all segments of the current route even if it has many. For example, a route("posts/:id") would have both :id and posts removed from the url. - "path": relative to the pathname so .. means remove one segment of the pathname. For example, a route("posts/:id") would have only :id removed from the url.

type RequestHandler

type RequestHandler = (
    request: Request,
    loadContext?: MiddlewareEnabled extends true
        ? RouterContextProvider
        : AppLoadContext
) => Promise<Response>;

type RevalidationState

type RevalidationState = 'idle' | 'loading';

type RouteObject

type RouteObject = IndexRouteObject | NonIndexRouteObject;

type RouteProps

type RouteProps = PathRouteProps | LayoutRouteProps | IndexRouteProps;

type RouterFetchOptions

type RouterFetchOptions = LoadFetchOptions | SubmitFetchOptions;

Options to pass to fetch()

type RouterNavigateOptions

type RouterNavigateOptions = LinkNavigateOptions | SubmissionNavigateOptions;

Options to pass to navigate() for a navigation

type ScriptsProps

type ScriptsProps = Omit<
    React.HTMLProps<HTMLScriptElement>,
    | 'async'
    | 'children'
    | 'dangerouslySetInnerHTML'
    | 'defer'
    | 'noModule'
    | 'src'
    | 'suppressHydrationWarning'
    | 'type'
> & {
    /**
     * A [`nonce`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce)
     * attribute to render on the [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
     * element
     */
    nonce?: string | undefined;
};

A couple common attributes:
- <Scripts crossOrigin> for hosting your static assets on a different server than your app. - <Scripts nonce> to support a [content security policy for scripts](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) with [nonce-sources](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources) for your [<script>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) tags.
You cannot pass through attributes such as [async](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/async), [defer](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/defer), [noModule](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/noModule), [src](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/src), or [type](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/type), because they are managed by React Router internally.
Types

type ScrollRestorationProps

type ScrollRestorationProps = ScriptsProps & {
    /**
     * A function that returns a key to use for scroll restoration. This is useful
     * for custom scroll restoration logic, such as using only the pathname so
     * that later navigations to prior paths will restore the scroll. Defaults to
     * `location.key`. See {@link GetScrollRestorationKeyFunction}.
     *
     * ```tsx
     * <ScrollRestoration
     *   getKey={(location, matches) => {
     *     // Restore based on a unique location key (default behavior)
     *     return location.key
     *
     *     // Restore based on pathname
     *     return location.pathname
     *   }}
     * />
     * ```
     */
    getKey?: GetScrollRestorationKeyFunction;
    /**
     * The key to use for storing scroll positions in [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
     * Defaults to `"react-router-scroll-positions"`.
     */
    storageKey?: string;
};

type SetURLSearchParams

type SetURLSearchParams = (
    nextInit?:
        | URLSearchParamsInit
        | ((prev: URLSearchParams) => URLSearchParamsInit),
    navigateOpts?: NavigateOptions
) => void;

Sets new search params and causes a navigation when called.
```tsx <button onClick={() => { const params = new URLSearchParams(); params.set("someKey", "someValue"); setSearchParams(params, { preventScrollReset: true, }); }} /> ```
It also supports a function for setting new search params.
```tsx <button onClick={() => { setSearchParams((prev) => { prev.set("someKey", "someValue"); return prev; }); }} /> ```

type SubmitTarget

type SubmitTarget =
    | HTMLFormElement
    | HTMLButtonElement
    | HTMLInputElement
    | FormData
    | URLSearchParams
    | JsonValue
    | null;

type To

type To = string | Partial<Path>;

Describes a location that is the destination of some navigation used in Link, useNavigate, etc.

type UNSAFE_MiddlewareEnabled

type MiddlewareEnabled = Future extends {
    v8_middleware: infer T extends boolean;
}
    ? T
    : false;

type unstable_BrowserCreateFromReadableStreamFunction

type BrowserCreateFromReadableStreamFunction = (
    body: ReadableStream<Uint8Array>,
    {
        temporaryReferences,
    }: {
        temporaryReferences: unknown;
    }
) => Promise<unknown>;

type unstable_ClientInstrumentation

type unstable_ClientInstrumentation = {
    router?: unstable_InstrumentRouterFunction;
    route?: unstable_InstrumentRouteFunction;
};

type unstable_DecodeActionFunction

type DecodeActionFunction = (formData: FormData) => Promise<() => Promise<unknown>>;

type unstable_DecodeFormStateFunction

type DecodeFormStateFunction = (result: unknown, formData: FormData) => unknown;

type unstable_DecodeReplyFunction

type DecodeReplyFunction = (
    reply: FormData | string,
    options: {
        temporaryReferences: unknown;
    }
) => Promise<unknown[]>;

type unstable_EncodeReplyFunction

type EncodeReplyFunction = (
    args: unknown[],
    options: {
        temporaryReferences: unknown;
    }
) => Promise<BodyInit>;

type unstable_InstrumentationHandlerResult

type unstable_InstrumentationHandlerResult =
    | {
          status: 'success';
          error: undefined;
      }
    | {
          status: 'error';
          error: Error;
      };

type unstable_InstrumentRequestHandlerFunction

type unstable_InstrumentRequestHandlerFunction = (
    handler: InstrumentableRequestHandler
) => void;

type unstable_InstrumentRouteFunction

type unstable_InstrumentRouteFunction = (route: InstrumentableRoute) => void;

type unstable_InstrumentRouterFunction

type unstable_InstrumentRouterFunction = (router: InstrumentableRouter) => void;

type unstable_LoadServerActionFunction

type LoadServerActionFunction = (id: string) => Promise<Function>;

type unstable_RSCManifestPayload

type RSCManifestPayload = {
    type: 'manifest';
    patches: RSCRouteManifest[];
};

type unstable_RSCMatch

type RSCMatch = {
    statusCode: number;
    headers: Headers;
    payload: RSCPayload;
};

type unstable_RSCPayload

type RSCPayload =
    | RSCRenderPayload
    | RSCManifestPayload
    | RSCActionPayload
    | RSCRedirectPayload;

type unstable_RSCRenderPayload

type RSCRenderPayload = {
    type: 'render';
    actionData: Record<string, any> | null;
    basename: string | undefined;
    errors: Record<string, any> | null;
    loaderData: Record<string, any>;
    location: Location;
    matches: RSCRouteMatch[];
    patches?: RSCRouteManifest[];
    nonce?: string;
    formState?: unknown;
};

type unstable_RSCRouteConfig

type RSCRouteConfig = Array<RSCRouteConfigEntry>;

type unstable_RSCRouteConfigEntry

type RSCRouteConfigEntry = RSCRouteConfigEntryBase & {
    id: string;
    path?: string;
    Component?: React.ComponentType<any>;
    lazy?: () => Promise<
        RSCRouteConfigEntryBase &
            (
                | {
                      default?: React.ComponentType<any>;
                      Component?: never;
                  }
                | {
                      default?: never;
                      Component?: React.ComponentType<any>;
                  }
            )
    >;
} & (
        | {
              index: true;
          }
        | {
              children?: RSCRouteConfigEntry[];
          }
    );

type unstable_RSCRouteManifest

type RSCRouteManifest = {
    clientAction?: ClientActionFunction;
    clientLoader?: ClientLoaderFunction;
    element?: React.ReactElement | false;
    errorElement?: React.ReactElement;
    handle?: any;
    hasAction: boolean;
    hasComponent: boolean;
    hasErrorBoundary: boolean;
    hasLoader: boolean;
    hydrateFallbackElement?: React.ReactElement;
    id: string;
    index?: boolean;
    links?: LinksFunction;
    meta?: MetaFunction;
    parentId?: string;
    path?: string;
    shouldRevalidate?: ShouldRevalidateFunction;
};

type unstable_RSCRouteMatch

type RSCRouteMatch = RSCRouteManifest & {
    params: Params;
    pathname: string;
    pathnameBase: string;
};

type unstable_SerializesTo

type unstable_SerializesTo<T> = {
    unstable__ReactRouter_SerializesTo: [T];
};

A brand that can be applied to a type to indicate that it will serialize to a specific type when transported to the client from a loader. Only use this if you have additional serialization/deserialization logic in your application.

type unstable_ServerInstrumentation

type unstable_ServerInstrumentation = {
    handler?: unstable_InstrumentRequestHandlerFunction;
    route?: unstable_InstrumentRouteFunction;
};

type unstable_SSRCreateFromReadableStreamFunction

type SSRCreateFromReadableStreamFunction = (
    body: ReadableStream<Uint8Array>
) => Promise<unknown>;

type URLSearchParamsInit

type URLSearchParamsInit =
    | string
    | ParamKeyValuePair[]
    | Record<string, string | string[]>
    | URLSearchParams;

Namespaces

namespace ScrollRestoration

namespace ScrollRestoration {}

variable displayName

var displayName: string;

namespace unstable_HistoryRouter

namespace unstable_HistoryRouter {}

variable displayName

var displayName: string;

Package Files (5)

Dependencies (2)

Dev Dependencies (13)

Peer Dependencies (2)

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/react-router.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/react-router)

HTML

<a href="https://www.jsdocs.io/package/react-router"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 1 second ago.
Package analyzed in 11000 ms.
Missing or incorrect documentation? Open an issue for this package.

react-router

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Enums

Type Aliases

Namespaces

Variables

variable createRequestHandler

variable createRoutesFromElements

Parameter children

Parameter parentPath

Returns

Example 1

Modifiers

variable createSession

variable Form

Parameter action

Parameter discover

Parameter encType

Parameter fetcherKey

Parameter method

Parameter navigate

Parameter onSubmit

Parameter preventScrollReset

Parameter relative

Parameter reloadDocument

Parameter replace

Parameter state

Parameter viewTransition

Parameter unstable_defaultShouldRevalidate

Returns

Example 1

Modifiers

variable IDLE_BLOCKER

variable IDLE_FETCHER

variable IDLE_NAVIGATION

variable isCookie

See Also

variable isSession

See Also

variable Link

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Example 1

Modifiers

variable NavLink

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Example 1

Modifiers

variable redirect

Parameter url

Parameter init

Returns