Remix Router
The @remix-run/router
package is a framework-agnostic routing package (sometimes referred to as a browser-emulator) that serves as the heart of React Router and Remix and provides all the core functionality for routing coupled with data loading and data mutations. It comes with built-in handling of errors, race-conditions, interruptions, cancellations, lazy-loading data, and much, much more.
If you're using React Router, you should never import
anything directly from the @remix-run/router
- you should have everything you need in react-router-dom
(or react-router
/react-router-native
if you're not rendering in the browser). All of those packages should re-export everything you would otherwise need from @remix-run/router
.
[!WARNING]
This router is a low-level package intended to be consumed by UI layer routing libraries. You should very likely not be using this package directly unless you are authoring a routing library such as react-router-dom
or one of it's other UI ports.
API
A Router instance can be created using createRouter
:
let router = createRouter({
routes: [{
path: '/',
loader: ({ request, params }) => { },
children: [{
path: 'home',
loader: ({ request, params }) => { },
}]
},
history: createBrowserHistory(),
basename,
mapRouteProperties,
future,
hydrationData,
}).initialize();
Internally, the Router represents the state in an object of the following format, which is available through router.state
. You can also register a subscriber of the signature (state: RouterState) => void
to execute when the state updates via router.subscribe()
;
interface RouterState {
initialized: boolean;
historyAction: Action;
location: Location;
matches: DataRouteMatch[];
navigation: Navigation;
revalidation: RevalidationState;
loaderData: RouteData;
actionData: RouteData | null;
errors: RouteData | null;
fetchers: Map<string, Fetcher>;
restoreScrollPosition: number | false | null;
preventScrollReset: boolean;
}
Navigations
All navigations are done through the router.navigate
API which is overloaded to support different types of navigations:
router.navigate("/page");
router.navigate("/page", { replace: true });
router.navigate(-1);
let formData = new FormData();
formData.append(key, value);
router.navigate("/page", {
formMethod: "post",
formData,
});
router.navigate("../../somewhere", {
fromRouteId: "active-route-id",
});
Fetchers
Fetchers are a mechanism to call loaders/actions without triggering a navigation, and are done through the router.fetch()
API. All fetch calls require a unique key to identify the fetcher.
router.fetch("key", "/page");
let formData = new FormData();
formData.append(key, value);
router.fetch("key", "/page", {
formMethod: "post",
formData,
});
Revalidation
By default, active loaders will revalidate after any navigation or fetcher mutation. If you need to kick off a revalidation for other use-cases, you can use router.revalidate()
to re-execute all active loaders.
Future Flags
We use Future Flags in the router to help us introduce breaking changes in an opt-in fashion ahead of major releases. Please check out the blog post and React Router Docs for more information on this process. The currently available future flags in @remix-run/router
are:
Flag | Description |
---|
v7_normalizeFormMethod | Normalize useNavigation().formMethod to be an uppercase HTTP Method |
v7_prependBasename | Prepend the basename to incoming router.navigate /router.fetch paths |