import * as React from "react"; import type { NavigateOptions, RouteContextObject } from "./context"; import { AwaitContext, DataRouterContext, DataRouterDataContext, DataRouterNavigationContext, DataRouterStateContext, FetchersContext, IsDataRouteContext, LocationContext, NavigationContext, RSCRouterContext, RouteContext, RouteErrorContext, RouteIdContext, } from "./context"; import type { Location, Path, To } from "./router/history"; import { Action as NavigationType, createPath, invariant, parsePath, warning, } from "./router/history"; import type { Blocker, BlockerFunction, RelativeRoutingType, Router as DataRouter, RevalidationState, NavigationStates, } from "./router/router"; import { hasInvalidProtocol, IDLE_BLOCKER } from "./router/router"; import type { DataRouteMatch, ParamParseKey, Params, PathMatch, PathPattern, RouteManifest, RouteMatch, RouteObject, TrackedPromise, UIMatch, } from "./router/utils"; import { ENABLE_DEV_WARNINGS, convertRouteMatchToUiMatch, decodePath, getResolveToMatches, getRoutePattern, isBrowser, isRouteErrorResponse, joinPaths, matchPath, matchRoutes, parseToInfo, resolveTo, stripBasename, } from "./router/utils"; import type { GetActionData, GetLoaderData, SerializeFrom, } from "./types/route-data"; import type { ClientOnErrorFunction } from "./components"; import type { RouteModules } from "./types/register"; import { decodeRedirectErrorDigest, decodeRouteErrorResponseDigest, } from "./errors"; import { getNavigatorCurrentUrl, validateNavigationTarget, } from "./router/navigation"; /** * Resolves a URL against the current {@link Location}. * * @example * import { useHref } from "react-router"; * * function SomeComponent() { * let href = useHref("some/where"); * // "/resolved/some/where" * } * * @public * @category Hooks * @param to The path to resolve * @param options Options * @param 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 */ export function useHref( to: To, { relative }: { relative?: RelativeRoutingType } = {}, ): string { invariant( useInRouterContext(), // TODO: This error is probably because they somehow have 2 versions of the // router loaded. We can help them understand how to avoid that. `useHref() may be used only in the context of a component.`, ); let { basename, navigator } = React.useContext(NavigationContext); let { hash, pathname, search } = useResolvedPath(to, { relative }); let joinedPathname = pathname; // If we're operating within a basename, prepend it to the pathname prior // to creating the href. If this is a root navigation, then just use the raw // basename which allows the basename to have full control over the presence // of a trailing slash on root links if (basename !== "/") { joinedPathname = pathname === "/" ? basename : joinPaths([basename, pathname]); } return navigator.createHref({ pathname: joinedPathname, search, hash }); } /** * Returns `true` if this component is a descendant of a {@link Router}, useful * to ensure a component is used within a {@link Router}. * * @public * @category Hooks * @mode framework * @mode data * @returns Whether the component is within a {@link Router} context */ export function useInRouterContext(): boolean { return React.useContext(LocationContext) != null; } /** * Returns the current {@link Location}. This can be useful if you'd like to * perform some side effect whenever it changes. * * @example * import * as React from 'react' * import { useLocation } from 'react-router' * * function SomeComponent() { * let location = useLocation() * * React.useEffect(() => { * // Google Analytics * ga('send', 'pageview') * }, [location]); * * return ( * // ... * ); * } * * @public * @category Hooks * @returns The current {@link Location} object */ export function useLocation(): Location { invariant( useInRouterContext(), // TODO: This error is probably because they somehow have 2 versions of the // router loaded. We can help them understand how to avoid that. `useLocation() may be used only in the context of a component.`, ); return React.useContext(LocationContext).location; } /** * Returns the current {@link Navigation} action which describes how the router * came to the current {@link Location}, either by a pop, push, or replace on * the [`History`](https://developer.mozilla.org/en-US/docs/Web/API/History) stack. * * @public * @category Hooks * @returns The current {@link NavigationType} (`"POP"`, `"PUSH"`, or `"REPLACE"`) */ export function useNavigationType(): NavigationType { return React.useContext(LocationContext).navigationType; } /** * Returns a {@link PathMatch} object if the given pattern matches the current URL. * This is useful for components that need to know "active" state, e.g. * {@link NavLink | ``}. * * @public * @category Hooks * @param pattern The pattern to match against the current {@link Location} * @returns The path match object if the pattern matches, `null` otherwise */ export function useMatch( pattern: PathPattern | Path, ): PathMatch> | null { invariant( useInRouterContext(), // TODO: This error is probably because they somehow have 2 versions of the // router loaded. We can help them understand how to avoid that. `useMatch() may be used only in the context of a component.`, ); let { pathname } = useLocation(); return React.useMemo( () => matchPath(pattern, decodePath(pathname)), [pathname, pattern], ); } /** * The interface for the `navigate` function returned from {@link useNavigate}. */ export interface NavigateFunction { (to: To, options?: NavigateOptions): void | Promise; (delta: number): void | Promise; } const navigateEffectWarning = `You should call navigate() in a React.useEffect(), not when ` + `your component is first rendered.`; /** * Returns a function that lets you navigate programmatically in the browser in * response to user interactions or effects. * * It's often better to use {@link 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 {@link 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 {@link 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`: **Deprecated.** Use React's [``](https://react.dev/reference/react/ViewTransition) component instead. See the [migration guide](../../how-to/view-transitions). * * @example * import { useNavigate } from "react-router"; * * function SomeComponent() { * let navigate = useNavigate(); * return ( * * ); * } * * @additionalExamples * ### Navigate to another path * * ```tsx * navigate("/some/route"); * navigate("/some/route?search=param"); * ``` * * ### Navigate with a {@link To} object * * All properties are optional. * * ```tsx * navigate( * { * pathname: "/some/route", * search: "?search=param", * hash: "#hash", * }, * { * state: { some: "state" }, * }, * ); * ``` * * If you use `state`, that will be available on the {@link Location} object on * the next page. Access it with `useLocation().state` (see {@link useLocation}). * * ### Navigate back or forward in the history stack * * ```tsx * // 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. * * ```tsx * navigate("/some/route", { replace: true }); * ``` * * ### Prevent Scroll Reset * * [MODES: framework, data] * * To prevent {@link ScrollRestoration | ``} from resetting * the scroll position, use the `preventScrollReset` option. * * ```tsx * 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`. 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: * * ```ts * // If using * declare module "react-router" { * interface NavigateFunction { * (to: To, options?: NavigateOptions): void; * (delta: number): void; * } * } * * // If using or Framework mode * declare module "react-router" { * interface NavigateFunction { * (to: To, options?: NavigateOptions): Promise; * (delta: number): Promise; * } * } * ``` * * @public * @category Hooks * @returns A navigate function for programmatic navigation */ export function useNavigate(): NavigateFunction { let isDataRoute = React.useContext(IsDataRouteContext); // Conditional usage is OK here because the usage of a data router is static // eslint-disable-next-line react-hooks/rules-of-hooks return isDataRoute ? useNavigateStable() : useNavigateUnstable(); } function useNavigateUnstable(): NavigateFunction { invariant( useInRouterContext(), // TODO: This error is probably because they somehow have 2 versions of the // router loaded. We can help them understand how to avoid that. `useNavigate() may be used only in the context of a component.`, ); let dataRouterContext = React.useContext(DataRouterContext); let { basename, navigator } = React.useContext(NavigationContext); let { matches } = React.useContext(RouteContext); let { pathname: locationPathname } = useLocation(); let routePathnamesJson = JSON.stringify(getResolveToMatches(matches)); let activeRef = React.useRef(false); React.useLayoutEffect(() => { activeRef.current = true; }); let navigate: NavigateFunction = React.useCallback( (to: To | number, options: NavigateOptions = {}) => { warning(activeRef.current, navigateEffectWarning); // Short circuit here since if this happens on first render the navigate // is useless because we haven't wired up our history listener yet if (!activeRef.current) return; if (typeof to === "number") { navigator.go(to); return; } let path = resolveTo( to, JSON.parse(routePathnamesJson), locationPathname, options.relative === "path", ); // If we're operating within a basename, prepend it to the pathname prior // to handing off to history (but only if we're not in a data router, // otherwise it'll prepend the basename inside of the router). // If this is a root navigation, then we navigate to the raw basename // which allows the basename to have full control over the presence of a // trailing slash on root links if (dataRouterContext == null && basename !== "/") { path.pathname = path.pathname === "/" ? basename : joinPaths([basename, path.pathname]); } validateNavigationTarget( typeof to === "string" ? to : createPath(to), navigator.createHref(path), getNavigatorCurrentUrl(navigator), "reject", ); (!!options.replace ? navigator.replace : navigator.push)( path, options.state, options, ); }, [ basename, navigator, routePathnamesJson, locationPathname, dataRouterContext, ], ); return navigate; } const OutletContext = React.createContext(null); /** * Returns the parent route {@link Outlet | ``}. * * 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 * {@link Outlet | ``}. * * ```tsx * // Parent route * function Parent() { * const [count, setCount] = React.useState(0); * return ; * } * ``` * * ```tsx * // Child route * import { useOutletContext } from "react-router"; * * function Child() { * const [count, setCount] = useOutletContext(); * const increment = () => setCount((c) => c + 1); * return ; * } * ``` * * 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: * * ```tsx filename=src/routes/dashboard.tsx lines=[14,20] * 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(null); * * return ( *
*

Dashboard

* *
* ); * } * * export function useUser() { * return useOutletContext(); * } * ``` * * ```tsx filename=src/routes/dashboard/messages.tsx lines=[1,4] * import { useUser } from "../dashboard"; * * export default function DashboardMessages() { * const { user } = useUser(); * return ( *
*

Messages

*

Hello, {user.name}!

*
* ); * } * ``` * * @public * @category Hooks * @returns The context value passed to the parent {@link Outlet} component */ export function useOutletContext(): Context { return React.useContext(OutletContext) as Context; } /** * Returns the element for the child route at this level of the route * hierarchy. Used internally by {@link Outlet | ``} to render child * routes. * * @public * @category Hooks * @param context The context to pass to the outlet * @returns The child route element or `null` if no child routes match */ export function useOutlet(context?: unknown): React.ReactElement | null { let outlet = React.useContext(RouteContext).outlet; return React.useMemo( () => outlet && ( {outlet} ), [outlet, context], ); } /** * 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"`. * * @example * import { useParams } from "react-router"; * * function SomeComponent() { * let params = useParams(); * params.postId; * } * * @additionalExamples * ### Basic Usage * * ```tsx * import { useParams } from "react-router"; * * // given a route like: * } />; * * // 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: * * ```tsx * import { useParams } from "react-router"; * * export default function Post() { * let params = useParams(); * return

Post: {params.postId}

; * } * ``` * * ### Multiple Params * * Patterns can have multiple params: * * ```tsx * "/posts/:postId/comments/:commentId"; * ``` * * All will be available in the params object: * * ```tsx * import { useParams } from "react-router"; * * export default function Post() { * let params = useParams(); * return ( *

* Post: {params.postId}, Comment: {params.commentId} *

* ); * } * ``` * * ### Catchall Params * * Catchall params are defined with `*`: * * ```tsx * "/files/*"; * ``` * * The matched value will be available in the params object as follows: * * ```tsx * import { useParams } from "react-router"; * * export default function File() { * let params = useParams(); * let catchall = params["*"]; * // ... * } * ``` * * You can destructure the catchall param: * * ```tsx * export default function File() { * let { "*": catchall } = useParams(); * console.log(catchall); * } * ``` * * @public * @category Hooks * @returns An object containing the dynamic route parameters */ export function useParams< ParamsOrKey extends string | Record = string, >(): Readonly< [ParamsOrKey] extends [string] ? Params : Partial > { let { matches } = React.useContext(RouteContext); let routeMatch = matches[matches.length - 1]; return (routeMatch?.params ?? {}) as any; } /** * Resolves the pathname of the given `to` value against the current * {@link Location}. Similar to {@link useHref}, but returns a * {@link Path} instead of a string. * * @example * 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; // "" * } * * @public * @category Hooks * @param to The path to resolve * @param options Options * @param 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 {@link Path} object with `pathname`, `search`, and `hash` */ export function useResolvedPath( to: To, { relative }: { relative?: RelativeRoutingType } = {}, ): Path { let { matches } = React.useContext(RouteContext); let { pathname: locationPathname } = useLocation(); let routePathnamesJson = JSON.stringify(getResolveToMatches(matches)); return React.useMemo( () => resolveTo( to, JSON.parse(routePathnamesJson), locationPathname, relative === "path", ), [to, routePathnamesJson, locationPathname, relative], ); } /** * Hook version of {@link 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. * * @example * import { useRoutes } from "react-router"; * * function App() { * let element = useRoutes([ * { * path: "/", * element: , * children: [ * { * path: "messages", * element: , * }, * { path: "tasks", element: }, * ], * }, * { path: "team", element: }, * ]); * * return element; * } * * @public * @category Hooks * @param routes An array of {@link RouteObject}s that define the route hierarchy * @param locationArg An optional {@link Location} object or pathname string to * use instead of the current {@link Location} * @returns A React element to render the matched route, or `null` if no routes matched */ export function useRoutes( routes: RouteObject[], locationArg?: Partial | string, ): React.ReactElement | null { return useRoutesImpl(routes, locationArg); } // Internal implementation with accept optional param for RouterProvider usage export function useRoutesImpl( routes: RouteObject[], locationArg?: Partial | string, dataRouterOpts?: { router: DataRouter; manifest: RouteManifest; state: DataRouter["state"]; isStatic: boolean; onError: ClientOnErrorFunction | undefined; }, ): React.ReactElement | null { invariant( useInRouterContext(), // TODO: This error is probably because they somehow have 2 versions of the // router loaded. We can help them understand how to avoid that. `useRoutes() may be used only in the context of a component.`, ); let { navigator } = React.useContext(NavigationContext); let { matches: parentMatches } = React.useContext(RouteContext); let routeMatch = parentMatches[parentMatches.length - 1]; let parentParams = routeMatch ? routeMatch.params : {}; let parentPathname = routeMatch ? routeMatch.pathname : "/"; let parentPathnameBase = routeMatch ? routeMatch.pathnameBase : "/"; let parentRoute = routeMatch && routeMatch.route; if (ENABLE_DEV_WARNINGS) { // You won't get a warning about 2 different under a // without a trailing *, but this is a best-effort warning anyway since we // cannot even give the warning unless they land at the parent route. // // Example: // // // {/* This route path MUST end with /* because otherwise // it will never match /blog/post/123 */} // } /> // } /> // // // function Blog() { // return ( // // } /> // // ); // } let parentPath = (parentRoute && parentRoute.path) || ""; warningOnce( parentPathname, !parentRoute || parentPath.endsWith("*") || parentPath.endsWith("*?"), `You rendered descendant (or called \`useRoutes()\`) at ` + `"${parentPathname}" (under ) but the ` + `parent route path has no trailing "*". This means if you navigate ` + `deeper, the parent won't match anymore and therefore the child ` + `routes will never render.\n\n` + `Please change the parent to .`, ); } let locationFromContext = useLocation(); let location; if (locationArg) { let parsedLocationArg = typeof locationArg === "string" ? parsePath(locationArg) : locationArg; invariant( parentPathnameBase === "/" || parsedLocationArg.pathname?.startsWith(parentPathnameBase), `When overriding the location using \`\` or \`useRoutes(routes, location)\`, ` + `the location pathname must begin with the portion of the URL pathname that was ` + `matched by all parent routes. The current pathname base is "${parentPathnameBase}" ` + `but pathname "${parsedLocationArg.pathname}" was given in the \`location\` prop.`, ); location = parsedLocationArg; } else { location = locationFromContext; } let pathname = location.pathname || "/"; let remainingPathname = pathname; if (parentPathnameBase !== "/") { // Determine the remaining pathname by removing the # of URL segments the // parentPathnameBase has, instead of removing based on character count. // This is because we can't guarantee that incoming/outgoing encodings/ // decodings will match exactly. // We decode paths before matching on a per-segment basis with // decodeURIComponent(), but we re-encode pathnames via `new URL()` so they // match what `window.location.pathname` would reflect. Those don't 100% // align when it comes to encoded URI characters such as % and &. // // So we may end up with: // pathname: "/descendant/a%25b/match" // parentPathnameBase: "/descendant/a%b" // // And the direct substring removal approach won't work :/ let parentSegments = parentPathnameBase.replace(/^\//, "").split("/"); let segments = pathname.replace(/^\//, "").split("/"); remainingPathname = "/" + segments.slice(parentSegments.length).join("/"); } let matches: RouteMatch[] | null; if (dataRouterOpts) { if (dataRouterOpts.state.matches.length) { // If we're in a data router with existing matches, use them but ensure we have the // latest route instances from the manifest in case elements have changed matches = dataRouterOpts.state.matches.map((m) => Object.assign(m, { route: dataRouterOpts.manifest[m.route.id] || m.route, }), ); } else { matches = dataRouterOpts.router.match(dataRouterOpts.state.location); } } else { matches = matchRoutes(routes, { pathname: remainingPathname }); } if (ENABLE_DEV_WARNINGS) { warning( parentRoute || matches != null, `No routes matched location "${location.pathname}${location.search}${location.hash}" `, ); warning( matches == null || matches[matches.length - 1].route.element !== undefined || matches[matches.length - 1].route.Component !== undefined || matches[matches.length - 1].route.lazy !== undefined, `Matched leaf route at location "${location.pathname}${location.search}${location.hash}" ` + `does not have an element or Component. This means it will render an with a ` + `null value by default resulting in an "empty" page.`, ); } let renderedMatches = _renderMatches( matches && matches.map((match) => Object.assign({}, match, { params: Object.assign({}, parentParams, match.params), pathname: joinPaths([ parentPathnameBase, // Re-encode pathnames that were decoded inside matchRoutes. // Pre-encode `%`, `?` and `#` ahead of `encodeLocation` because it uses // `new URL()` internally and we need to prevent it from treating // them as separators navigator.encodeLocation ? navigator.encodeLocation( match.pathname .replace(/%/g, "%25") .replace(/\?/g, "%3F") .replace(/#/g, "%23"), ).pathname : match.pathname, ]), pathnameBase: match.pathnameBase === "/" ? parentPathnameBase : joinPaths([ parentPathnameBase, // Re-encode pathnames that were decoded inside matchRoutes // Pre-encode `%`, `?` and `#` ahead of `encodeLocation` because it uses // `new URL()` internally and we need to prevent it from treating // them as separators navigator.encodeLocation ? navigator.encodeLocation( match.pathnameBase .replace(/%/g, "%25") .replace(/\?/g, "%3F") .replace(/#/g, "%23"), ).pathname : match.pathnameBase, ]), }), ), parentMatches, dataRouterOpts, ); // When a user passes in a `locationArg`, the associated routes need to // be wrapped in a new `LocationContext.Provider` in order for `useLocation` // to use the scoped location instead of the global location. if (locationArg && renderedMatches) { return ( {renderedMatches} ); } return renderedMatches; } function DefaultErrorComponent() { let error = useRouteError(); let message = isRouteErrorResponse(error) ? `${error.status} ${error.statusText}` : error instanceof Error ? error.message : JSON.stringify(error); let stack = error instanceof Error ? error.stack : null; let lightgrey = "rgba(200,200,200, 0.5)"; let preStyles = { padding: "0.5rem", backgroundColor: lightgrey }; let codeStyles = { padding: "2px 4px", backgroundColor: lightgrey }; let devInfo = null; if (ENABLE_DEV_WARNINGS) { console.error( "Error handled by React Router default ErrorBoundary:", error, ); devInfo = ( <>

💿 Hey developer 👋

You can provide a way better UX than this when your app throws errors by providing your own ErrorBoundary or{" "} errorElement prop on your route.

); } return ( <>

Unexpected Application Error!

{message}

{stack ?
{stack}
: null} {devInfo} ); } const defaultErrorElement = ; type RenderErrorBoundaryProps = React.PropsWithChildren<{ location: Location; revalidation: RevalidationState; error: any; component: React.ReactNode; routeContext: RouteContextObject; onError?: (error: unknown, errorInfo?: React.ErrorInfo) => void; }>; type RenderErrorBoundaryState = { location: Location; revalidation: RevalidationState; error: any; }; export class RenderErrorBoundary extends React.Component< RenderErrorBoundaryProps, RenderErrorBoundaryState > { constructor(props: RenderErrorBoundaryProps) { super(props); this.state = { location: props.location, revalidation: props.revalidation, error: props.error, }; } static contextType = RSCRouterContext; static getDerivedStateFromError(error: any) { return { error: error }; } static getDerivedStateFromProps( props: RenderErrorBoundaryProps, state: RenderErrorBoundaryState, ) { // When we get into an error state, the user will likely click "back" to the // previous page that didn't have an error. Because this wraps the entire // application, that will have no effect--the error page continues to display. // This gives us a mechanism to recover from the error when the location changes. // // Whether we're in an error state or not, we update the location in state // so that when we are in an error state, it gets reset when a new location // comes in and the user recovers from the error. if ( state.location !== props.location || (state.revalidation !== "idle" && props.revalidation === "idle") ) { return { error: props.error, location: props.location, revalidation: props.revalidation, }; } // If we're not changing locations, preserve the location but still surface // any new errors that may come through. We retain the existing error, we do // this because the error provided from the app state may be cleared without // the location changing. return { error: props.error !== undefined ? props.error : state.error, location: state.location, revalidation: props.revalidation || state.revalidation, }; } componentDidCatch(error: any, errorInfo: React.ErrorInfo) { if (this.props.onError) { this.props.onError(error, errorInfo); } else { console.error( "React Router caught the following error during render", error, ); } } render() { let error = this.state.error; if ( this.context && typeof error === "object" && error && "digest" in error && typeof error.digest === "string" ) { const decoded = decodeRouteErrorResponseDigest(error.digest); if (decoded) error = decoded; } let result = error !== undefined ? ( ) : ( this.props.children ); if (this.context) { return {result}; } return result; } } const errorRedirectHandledMap = new WeakMap>(); function RSCErrorHandler({ children, error, }: { children: React.ReactNode; error: unknown; }) { let { basename, navigator } = React.useContext(NavigationContext); if ( typeof error === "object" && error && "digest" in error && typeof error.digest === "string" ) { let redirect = decodeRedirectErrorDigest(error.digest); if (redirect) { let existingRedirect = errorRedirectHandledMap.get(error); if (existingRedirect) throw existingRedirect; let parsed = parseToInfo(redirect.location, basename); let target = parsed.absoluteURL || parsed.to; validateNavigationTarget( redirect.location, target, getNavigatorCurrentUrl(navigator), "allow-explicit", ); if (hasInvalidProtocol(target)) { throw new Error("Invalid redirect location"); } if (isBrowser && !errorRedirectHandledMap.get(error)) { if (parsed.isExternal || redirect.reloadDocument) { window.location.href = target; } else { const redirectPromise: Promise = Promise.resolve().then(() => window.__reactRouterDataRouter!.navigate(parsed.to, { replace: redirect.replace, }), ); errorRedirectHandledMap.set(error, redirectPromise); throw redirectPromise; } } return ; } } return children; } interface RenderedRouteProps { routeContext: RouteContextObject; match: RouteMatch; children: React.ReactNode | null; } function RenderedRoute({ routeContext, match, children }: RenderedRouteProps) { let dataRouterContext = React.useContext(DataRouterContext); // Track how deep we got in our render pass to emulate SSR componentDidCatch // in a DataStaticRouter if ( dataRouterContext && dataRouterContext.static && dataRouterContext.staticContext && (match.route.errorElement || match.route.ErrorBoundary) ) { dataRouterContext.staticContext._deepestRenderedBoundaryId = match.route.id; } return ( {children} ); } export function _renderMatches( matches: RouteMatch[] | null, parentMatches: RouteMatch[] = [], dataRouterOpts?: { state: DataRouter["state"]; isStatic: boolean; onError: ClientOnErrorFunction | undefined; }, ): React.ReactElement | null { let dataRouterState = dataRouterOpts?.state; if (matches == null) { if (!dataRouterState) { return null; } if (dataRouterState.errors) { // Don't bail if we have data router errors so we can render them in the // boundary. Use the pre-matched (or shimmed) matches matches = dataRouterState.matches as DataRouteMatch[]; } else if ( parentMatches.length === 0 && !dataRouterState.initialized && dataRouterState.matches.length > 0 ) { // Don't bail if we're initializing with partial hydration and we have // router matches. That means we're actively running `patchRoutesOnNavigation` // so we should render down the partial matches to the appropriate // `HydrateFallback`. We only do this if `parentMatches` is empty so it // only impacts the root matches for `RouterProvider` and no descendant // `` matches = dataRouterState.matches as DataRouteMatch[]; } else { return null; } } let renderedMatches = matches; // If we have data errors, trim matches to the highest error boundary let errors = dataRouterState?.errors; if (errors != null) { let errorIndex = renderedMatches.findIndex( (m) => m.route.id && errors?.[m.route.id] !== undefined, ); invariant( errorIndex >= 0, `Could not find a matching route for errors on route IDs: ${Object.keys( errors, ).join(",")}`, ); renderedMatches = renderedMatches.slice( 0, Math.min(renderedMatches.length, errorIndex + 1), ); } // If we're in a partial hydration mode, detect if we need to render down to // a given HydrateFallback while we load the rest of the hydration data let renderFallback = false; let fallbackIndex = -1; if (dataRouterOpts && dataRouterState) { renderFallback = dataRouterState.renderFallback; for (let i = 0; i < renderedMatches.length; i++) { let match = renderedMatches[i]; // Track the deepest fallback up until the first route without data if (match.route.HydrateFallback || match.route.hydrateFallbackElement) { fallbackIndex = i; } if (match.route.id) { let { loaderData, errors } = dataRouterState; let needsToRunLoader = match.route.loader && !loaderData.hasOwnProperty(match.route.id) && (!errors || errors[match.route.id] === undefined); if (match.route.lazy || needsToRunLoader) { // We found the first route that's not ready to render (waiting on // lazy, or has a loader that hasn't run yet) - render up until the // appropriate fallback if (dataRouterOpts.isStatic) { renderFallback = true; } if (fallbackIndex >= 0) { renderedMatches = renderedMatches.slice(0, fallbackIndex + 1); } else { renderedMatches = [renderedMatches[0]]; } break; } } } } let onErrorHandler = dataRouterOpts?.onError; let onError = dataRouterState && onErrorHandler ? (error: unknown, errorInfo?: React.ErrorInfo) => { onErrorHandler(error, { location: dataRouterState.location, params: dataRouterState.matches?.[0]?.params ?? {}, pattern: getRoutePattern(dataRouterState.matches), errorInfo, }); } : undefined; return renderedMatches.reduceRight( (outlet, match, index) => { // Only data routers handle errors/fallbacks let error: any; let shouldRenderHydrateFallback = false; let errorElement: React.ReactNode | null = null; let hydrateFallbackElement: React.ReactNode | null = null; if (dataRouterState) { error = errors && match.route.id ? errors[match.route.id] : undefined; errorElement = match.route.errorElement || defaultErrorElement; if (renderFallback) { if (fallbackIndex < 0 && index === 0) { warningOnce( "route-fallback", false, "No `HydrateFallback` element provided to render during initial hydration", ); shouldRenderHydrateFallback = true; hydrateFallbackElement = null; } else if (fallbackIndex === index) { shouldRenderHydrateFallback = true; hydrateFallbackElement = match.route.hydrateFallbackElement || null; } } } let matches = parentMatches.concat(renderedMatches.slice(0, index + 1)); let getChildren = () => { let children: React.ReactNode; if (error) { children = errorElement; } else if (shouldRenderHydrateFallback) { children = hydrateFallbackElement; } else if (match.route.Component) { // Note: This is a de-optimized path since React won't re-use the // ReactElement since it's identity changes with each new // React.createElement call. We keep this so folks can use // `` in `` but generally `Component` // usage is only advised in `RouterProvider` when we can convert it to // `element` ahead of time. children = ; } else if (match.route.element) { children = match.route.element; } else { children = outlet; } return ( ); }; // Only wrap in an error boundary within data router usages when we have an // ErrorBoundary/errorElement on this route. Otherwise let it bubble up to // an ancestor ErrorBoundary/errorElement return dataRouterState && (match.route.ErrorBoundary || match.route.errorElement || index === 0) ? ( ) : ( getChildren() ); }, null as React.ReactElement | null, ); } function getDataRouterConsoleError(hookName: string) { return `${hookName} must be used within a data router. See https://reactrouter.com/en/main/routers/picking-a-router.`; } export function useDataRouterContext(hookName: string) { let ctx = React.useContext(DataRouterContext); invariant(ctx, getDataRouterConsoleError(hookName)); return ctx; } export function useDataRouterState(hookName: string) { let state = React.useContext(DataRouterStateContext); invariant(state, getDataRouterConsoleError(hookName)); return state; } export function useDataRouterFetchers(hookName: string) { let fetchers = React.useContext(FetchersContext); invariant(fetchers, getDataRouterConsoleError(hookName)); return fetchers; } export function useDataRouterData(hookName: string) { let data = React.useContext(DataRouterDataContext); invariant(data, getDataRouterConsoleError(hookName)); return data; } function useDataRouterNavigation(hookName: string) { let navigation = React.useContext(DataRouterNavigationContext); invariant(navigation, getDataRouterConsoleError(hookName)); return navigation; } // Internal helper with hookName-aware debugging export function useCurrentRouteId(hookName: string) { let routeId = React.useContext(RouteIdContext); invariant( routeId, `${hookName} can only be used on routes that contain a unique "id"`, ); return routeId; } // Omit the fields from each navigation state individually to preserve the discriminated union type UseNavigationResult = UseNavigationResultStates[keyof UseNavigationResultStates]; type UseNavigationResultStates = { Idle: Omit; Loading: Omit; Submitting: Omit; }; /** * Returns the current {@link 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. * * @example * import { useNavigation } from "react-router"; * * function SomeComponent() { * let navigation = useNavigation(); * navigation.state; * navigation.formData; * // etc. * } * * @public * @category Hooks * @mode framework * @mode data * @returns The current {@link Navigation} object */ export function useNavigation(): UseNavigationResult { let { navigation } = useDataRouterNavigation("useNavigation"); return React.useMemo(() => { let { matches, historyAction, ...rest } = navigation; return rest; }, [navigation]); } /** * 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 {@link useFetcher}, {@link Form}, {@link useSubmit} that do * this automatically. * * @example * import { useRevalidator } from "react-router"; * * function WindowFocusRevalidator() { * const revalidator = useRevalidator(); * * useFakeWindowFocus(() => { * revalidator.revalidate(); * }); * * return ( * * ); * } * * @public * @category Hooks * @mode framework * @mode data * @returns An object with a `revalidate` function and the current revalidation * `state` */ export function useRevalidator(): { revalidate: () => Promise; state: DataRouter["state"]["revalidation"]; } { let dataRouterContext = useDataRouterContext("useRevalidator"); let { revalidation } = useDataRouterNavigation("useRevalidator"); let revalidate = React.useCallback(async () => { await dataRouterContext.router.revalidate(); }, [dataRouterContext.router]); return React.useMemo( () => ({ revalidate, state: revalidation }), [revalidate, revalidation], ); } /** * Returns the active route matches, useful for accessing `loaderData` for * parent/child routes or the route [`handle`](../../start/framework/route-module#handle) * property * * Pairing the route `handle` with `useMatches` gets very powerful since you can put * whatever you want on a route handle and have access to `useMatches` anywhere. * Please see the [handle](../../how-to/using-handle) documentation for an example * of breadcrumbs via `useMatches`/`handle`. * * ```tsx * import { useMatches } from "react-router"; * * function SomeComponent() { * const matches = useMatches(); * // matches[i].id // route id * // matches[i].pathname // the portion of the URL the route matched * // matches[i].params // the parsed params from the URL * // matches[i].loaderData // the data from the loader * // matches[i].handle // the route handle with any app specific data * } * ``` * * useMatches only works with a data router like `createBrowserRouter`, * since they know the full route tree up front and can provide all of the current * matches. Additionally, `useMatches` will not match down into any descendant route * trees since the router isn't aware of the descendant routes. * * @public * @category Hooks * @mode framework * @mode data * @returns An array of {@link UIMatch | UI matches} for the current route hierarchy */ export function useMatches(): UIMatch[] { let { matches } = useDataRouterState("useMatches"); let { loaderData } = useDataRouterData("useMatches"); return React.useMemo( () => matches.map((m) => convertRouteMatchToUiMatch(m, loaderData)), [matches, loaderData], ); } /** * Returns the data from the closest route * [`loader`](../../start/framework/route-module#loader) or * [`clientLoader`](../../start/framework/route-module#clientloader). * * @example * import { useLoaderData } from "react-router"; * * export async function loader() { * return await fakeDb.invoices.findAll(); * } * * export default function Invoices() { * let invoices = useLoaderData(); * // ... * } * * @public * @category Hooks * @mode framework * @mode data * @returns The data returned from the route's [`loader`](../../start/framework/route-module#loader) or [`clientLoader`](../../start/framework/route-module#clientloader) function */ export function useLoaderData(): SerializeFrom { let data = useDataRouterData("useLoaderData"); let routeId = useCurrentRouteId("useLoaderData"); return data.loaderData[routeId] as SerializeFrom; } /** * 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"` | * * @example * 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"); * * @public * @category Hooks * @mode framework * @mode data * @param 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 */ export function useRouteLoaderData( routeId: string, ): SerializeFrom | undefined { let data = useDataRouterData("useRouteLoaderData"); return data.loaderData[routeId] as SerializeFrom | 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. * * @example * 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..."} *
* ); * } * * @public * @category Hooks * @mode framework * @mode data * @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 */ export function useActionData(): SerializeFrom | undefined { let data = useDataRouterData("useActionData"); let routeId = useCurrentRouteId("useActionData"); return (data.actionData ? data.actionData[routeId] : undefined) as | SerializeFrom | undefined; } /** * 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). * * @example * export function ErrorBoundary() { * const error = useRouteError(); * return
{error.message}
; * } * * @public * @category Hooks * @mode framework * @mode data * @returns The error that was thrown during route [loading](../../start/framework/route-module#loader), * [`action`](../../start/framework/route-module#action) execution, or rendering */ export function useRouteError(): unknown { let error = React.useContext(RouteErrorContext); let data = useDataRouterData("useRouteError"); let routeId = useCurrentRouteId("useRouteError"); // If this was a render error, we put it in a RouteError context inside // of RenderErrorBoundary if (error !== undefined) { return error; } // Otherwise look for errors from our data router data return data.errors?.[routeId]; } /** * Returns the resolved promise value from the closest {@link Await | ``}. * * @example * function SomeDescendant() { * const value = useAsyncValue(); * // ... * } * * // somewhere in your app * * * ; * * @public * @category Hooks * @mode framework * @mode data * @returns The resolved value from the nearest {@link Await} component */ export function useAsyncValue(): unknown { let value = React.useContext(AwaitContext); return value && "status" in value && !("_tracked" in value) ? value.status === "fulfilled" ? value.value : undefined : (value as TrackedPromise | null)?._data; } /** * Returns the rejection value from the closest {@link Await | ``}. * * @example * import { Await, useAsyncError } from "react-router"; * * function ErrorElement() { * const error = useAsyncError(); * return ( *

Uh Oh, something went wrong! {error.message}

* ); * } * * // somewhere in your app * } * />; * * @public * @category Hooks * @mode framework * @mode data * @returns The error that was thrown in the nearest {@link Await} component */ export function useAsyncError(): unknown { let value = React.useContext(AwaitContext); return value && "status" in value && !("_tracked" in value) ? value.status === "rejected" ? value.reason : undefined : (value as TrackedPromise | null)?._error; } let blockerId = 0; /** * 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 {@link 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 {@link 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. * * @example * // Boolean version * let blocker = useBlocker(value !== ""); * * // Function version * let blocker = useBlocker( * ({ currentLocation, nextLocation, historyAction }) => * value !== "" && * currentLocation.pathname !== nextLocation.pathname * ); * * @additionalExamples * ```tsx * import { useCallback, useState } from "react"; * import { BlockerFunction, useBlocker } from "react-router"; * * export function ImportantForm() { * const [value, setValue] = useState(""); * * const shouldBlock = useCallback( * () => value !== "", * [value] * ); * const blocker = useBlocker(shouldBlock); * * return ( *
{ * e.preventDefault(); * setValue(""); * if (blocker.state === "blocked") { * blocker.proceed(); * } * }} * > * setValue(e.target.value)} * /> * * * * {blocker.state === "blocked" ? ( * <> *

* Blocked the last navigation to *

* * * * ) : blocker.state === "proceeding" ? ( *

* Proceeding through blocked navigation *

* ) : ( *

* Blocker is currently unblocked *

* )} *
* ); * } * ``` * * @public * @category Hooks * @mode framework * @mode data * @param 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 {@link Blocker} object with state and reset functionality */ export function useBlocker(shouldBlock: boolean | BlockerFunction): Blocker { let { router, basename } = useDataRouterContext("useBlocker"); let state = useDataRouterState("useBlocker"); let [blockerKey, setBlockerKey] = React.useState(""); let blockerFunction = React.useCallback( (arg) => { if (typeof shouldBlock !== "function") { return !!shouldBlock; } if (basename === "/") { return shouldBlock(arg); } // If they provided us a function and we've got an active basename, strip // it from the locations we expose to the user to match the behavior of // useLocation let { currentLocation, nextLocation, historyAction } = arg; return shouldBlock({ currentLocation: { ...currentLocation, pathname: stripBasename(currentLocation.pathname, basename) || currentLocation.pathname, }, nextLocation: { ...nextLocation, pathname: stripBasename(nextLocation.pathname, basename) || nextLocation.pathname, }, historyAction, }); }, [basename, shouldBlock], ); // The key owned by the currently mounted effect below. `blockerKey` state // survives the effect being torn down and set up again (i.e., `` // hiding and showing the component, or a new `router`), so it can briefly // point at a key that has already been deleted. let activeBlockerKey = React.useRef(""); // This effect is in charge of blocker key assignment and deletion (which is // tightly coupled to the key) React.useEffect(() => { let key = String(++blockerId); activeBlockerKey.current = key; setBlockerKey(key); return () => { activeBlockerKey.current = ""; router.deleteBlocker(key); }; }, [router]); // This effect handles assigning the blockerFunction. This is to handle // unstable blocker function identities, and happens only after the prior // effect so we don't get an orphaned blockerFunction in the router with a // key of "". Until then we just have the IDLE_BLOCKER. It also skips a // stale `blockerKey` so a deleted key is never registered again. React.useEffect(() => { if (blockerKey !== "" && blockerKey === activeBlockerKey.current) { router.getBlocker(blockerKey, blockerFunction); } }, [router, blockerKey, blockerFunction]); // Prefer the blocker from `state` not `router.state` since DataRouterContext // is memoized so this ensures we update on blocker state updates return blockerKey && state.blockers.has(blockerKey) ? state.blockers.get(blockerKey)! : IDLE_BLOCKER; } // Stable version of useNavigate that is used when we are in the context of // a RouterProvider. function useNavigateStable(): NavigateFunction { let { router } = useDataRouterContext("useNavigate"); let id = useCurrentRouteId("useNavigate"); let activeRef = React.useRef(false); React.useLayoutEffect(() => { activeRef.current = true; }); let navigate: NavigateFunction = React.useCallback( async (to: To | number, options: NavigateOptions = {}) => { warning(activeRef.current, navigateEffectWarning); // Short circuit here since if this happens on first render the navigate // is useless because we haven't wired up our router subscriber yet if (!activeRef.current) return; if (typeof to === "number") { await router.navigate(to); } else { await router.navigate(to, { fromRouteId: id, ...options }); } }, [router, id], ); return navigate; } const alreadyWarned: Record = {}; function warningOnce(key: string, cond: boolean, message: string) { if (!cond && !alreadyWarned[key]) { alreadyWarned[key] = true; warning(false, message); } } type UseRouteArgs = [] | [routeId: keyof RouteModules]; // prettier-ignore type UseRouteResult = Args extends [] ? UseRoute : Args extends ["root"] ? UseRoute<"root"> : Args extends [infer RouteId extends keyof RouteModules] ? UseRoute | undefined : never; // prettier-ignore type UseRoute = { handle: RouteId extends keyof RouteModules ? RouteModules[RouteId] extends { handle: infer handle } ? handle : unknown : unknown; loaderData: RouteId extends keyof RouteModules ? GetLoaderData | undefined : unknown; actionData: RouteId extends keyof RouteModules ? GetActionData | undefined : unknown; }; export function useRoute( ...args: Args ): UseRouteResult { const currentRouteId: keyof RouteModules = useCurrentRouteId("useRoute"); const id: keyof RouteModules = args[0] ?? currentRouteId; const state = useDataRouterState("useRoute"); const data = useDataRouterData("useRoute"); const route = state.matches.find(({ route }) => route.id === id); if (route === undefined) return undefined as UseRouteResult; return { handle: route.route.handle, loaderData: data.loaderData[id], actionData: data.actionData?.[id], } as UseRouteResult; } /** * A single route match returned from {@link unstable_useRouterState}. Mirrors * {@link UIMatch} minus the data-related fields (`data`, `loaderData`). */ type unstable_RouterStateMatch = Omit< UIMatch, "data" | "loaderData" >; /** * The shape of the `active` variant returned from * {@link unstable_useRouterState}. */ export type unstable_RouterStateActiveVariant = { location: Location; searchParams: URLSearchParams; params: Params; matches: unstable_RouterStateMatch[]; type: NavigationType; }; /** * The shape of the `pending` variant returned from * {@link unstable_useRouterState}. Extends * {@link unstable_RouterStateActiveVariant} with the navigation `state` and * submission fields mirroring {@link useNavigation} — submission fields are * populated when the in-flight navigation was triggered by a form submission, * otherwise `undefined`. */ export type unstable_RouterStatePendingVariant = unstable_RouterStatePendingVariants[keyof unstable_RouterStatePendingVariants]; type unstable_RouterStatePendingVariants = { Loading: unstable_RouterStateActiveVariant & Omit; Submitting: unstable_RouterStateActiveVariant & Omit; }; /** * The return shape of {@link unstable_useRouterState}. * * `active` reflects the currently-committed location. `pending` reflects the * in-flight navigation (if any). */ export type unstable_RouterState = { active: unstable_RouterStateActiveVariant; pending: unstable_RouterStatePendingVariant | null; }; function toRouterStateMatch(match: DataRouteMatch): unstable_RouterStateMatch { return { id: match.route.id, pathname: match.pathname, params: match.params, handle: match.route.handle, }; } /** * A unified hook for reading router state: current (`active`) and in-flight * (`pending`) locations, search params, params, matches, and navigation type. * * This hook consolidates the information you used to get from {@link useLocation}, * {@link useSearchParams}, {@link useParams}, {@link useMatches}, {@link useNavigation}, * and {@link useNavigationType} into a single hook. * * * @example * import { unstable_useRouterState as useRouterState } from "react-router"; * * let { active, pending } = useRouterState(); * * // Active is always populated with the current location * active.location; // replaces `useLocation()` * active.searchParams; // replaces `useSearchParams()[0]` * active.params; // replaces `useParams()` * active.matches; // replaces `useMatches()` * active.type; // replaces `useNavigationType()` * * // Pending is only populated during a navigation * pending.location; // replaces `useNavigation().location` * pending.searchParams; // equivalent to `new URLSearchParams(useNavigation().search)` * pending.params; // Not directly accessible today * pending.matches; // Not directly accessible today * pending.type; // Not directly accessible today * pending.state; // replaces `useNavigation().state` * pending.formMethod; // replaces useNavigation().formMethod * pending.formAction; // replaces useNavigation().formAction * pending.formEncType; // replaces useNavigation().formEncType * pending.formData; // replaces useNavigation().formData * pending.json; // replaces useNavigation().json * pending.text; // replaces useNavigation().text * * @name unstable_useRouterState * @public * @category Hooks * @mode framework * @mode data * @returns The current router state with `active` and `pending` variants */ export function useRouterState(): unstable_RouterState { let { location, historyAction: type, matches, } = useDataRouterState("unstable_useRouterState"); let { navigation } = useDataRouterNavigation("unstable_useRouterState"); let active = React.useMemo( () => ({ type, location, searchParams: new URLSearchParams(location.search), params: matches[matches.length - 1]?.params ?? {}, matches: matches.map((m) => toRouterStateMatch(m)), }), [location, matches, type], ); let pending = React.useMemo(() => { if (navigation.state === "idle") return null; let shared = { type: navigation.historyAction, location: navigation.location, searchParams: new URLSearchParams(navigation.location.search), params: navigation.matches[navigation.matches.length - 1]?.params ?? {}, matches: navigation.matches.map((m) => toRouterStateMatch(m)), }; // Do submissions fields independently to keep TS happy with the // `NavigationStates` discriminated union return navigation.state === "loading" ? { ...shared, state: "loading", formMethod: navigation.formMethod, formAction: navigation.formAction, formEncType: navigation.formEncType, formData: navigation.formData, json: navigation.json, text: navigation.text, } : { ...shared, state: "submitting", formMethod: navigation.formMethod, formAction: navigation.formAction, formEncType: navigation.formEncType, formData: navigation.formData, json: navigation.json, text: navigation.text, }; }, [navigation]); return React.useMemo( () => ({ active, pending }), [active, pending], ); }