Data Loading

One of the primary features of Remix is simplifying interactions with the server to get data into components. When you follow these conventions, Remix can automatically:

  • Server render your pages
  • Be resilient to network conditions when JavaScript fails to load
  • Make optimizations as the user interacts with your site to make it fast by only loading data for the changing parts of the page
  • Fetch data, JavaScript modules, CSS and other assets in parallel on transitions, avoiding render+fetch waterfalls that lead to choppy UI
  • Ensure the data in the UI is in sync with the data on the server by revalidating after actions
  • Excellent scroll restoration on back/forward clicks (even across domains)
  • Handle server side errors with error boundaries
  • Enable solid UX for “Not Found” and “Unauthorized” with catch boundaries
  • Help you keep the happy path of your UI happy.

Basics

Each route module can export a component and a loader. useLoaderData will provide the loader’s data to your component:

  1. import { useLoaderData } from "remix";
  2. import type { LoaderFunction } from "remix";
  4. export let loader: LoaderFunction = () => {
  5.   return [{ name: "Pants" }, { name: "Jacket" }];
  6. };
  8. export default function Products() {
  9.   let products = useLoaderData();
  10.   return (
  11.     <div>
  12.       <h1>Products</h1>
  13.       {products.map(product => (
  14.         <div>{product.name}</div>
  15.       ))}
  16.     </div>
  17.   );
  18. }

The component renders on the server and in the browser. The loader only runs on the server. That means our hard-coded products array doesn’t get included in the browser bundles and it’s safe to use server-only for APIs and SDKs for things like database, payment processing, content management systems, etc.

If your server side modules end up in client bundles, move the imports for those modules to a file named {something}.server.ts with the .server.ts suffix to ensure they are excluded.

Route Params

When you name a file with $ like routes/users/$userId.tsx and routes/users/$userId/projects/$projectId.tsx the dynamic segments (the ones starting with $) will be parsed from the URL and passed to your loader on a params object.

  1. import type { LoaderFunction } from "remix";
  3. export let loader: LoaderFunction = ({ params }) => {
  4.   console.log(params.userId);
  5.   console.log(params.projectId);
  6. };

Given the following URLs, the params would be parsed as follows:

URLparams.userIdparams.projectId
/users/123/projects/abc“123”“abc”
/users/aec34g/projects/22cba9“aec34g”“22cba9”

These params are most useful for looking up data:

  1. import type { LoaderFunction } from "remix";
  3. export let loader: LoaderFunction = ({ params }) => {
  4.   return fakeDb.project.findMany({
  5.     where: {
  6.       userId: params.userId,
  7.       projectId: params.projectId
  8.     }
  9.   });
  10. };

Param Type Safety

Because these params come from the URL and not your source code, you can’t know for sure if they will be defined. That’s why the types on the param’s keys are string | undefined. It’s good practice to validate before using them, especially in TypeScript to get type safety. Using invariant makes it easy.

  1. import invariant from "tiny-invariant";
  2. import type { LoaderFunction } from "remix";
  4. export let loader: LoaderFunction = ({ params }) => {
  5.   invariant(params.userId, "Expected params.userId");
  6.   invariant(params.projectId, "Expected params.projectId");
  8.   params.projectId; // <-- TypeScript now knows this is a string
  9. };

While you may be uncomfortable throwing errors like this with invariant when it fails, remember that in Remix you know the user will end up in the error boundary where they can recover from the problem instead of a broken UI.

External APIs

Remix polyfills the fetch API on your server so it’s very easy to fetch data from existing JSON APIs. Instead of managing state, errors, race conditions, and more yourself, you can do the fetch from your loader (on the server) and let Remix handle the rest.

  1. export function loader() {
  2.   let res = fetch("https://api.gitub.com/gists");
  3.   return res.json();
  4. }
  6. export default function GistsRoute() {
  7.   let gists = useLoaderData();
  8.   return (
  9.     <ul>
  10.       {gists.map(gist => (
  11.         <li>
  12.           <a href={gist.html_url}>{gist.id}</a>
  13.         </li>
  14.       ))}
  15.     </ul>
  16.   );
  17. }

This is great when you already have an API to work with and don’t care or need to connect directly to your data source in your Remix app.

Databases

Since Remix runs on your server, you can connect directly to a database in your route modules. For example, you could connect to a Postgres database with Prisma.

  1. import { PrismaClient } from "@prisma/client";
  2. let db = new PrismaClient();
  3. export { db };

And then your routes can import it and make queries against it:

  1. import { useLoaderData } from "remix";
  2. import type { LoaderFunction } from "remix";
  3. import { db } from "~/db.server";
  5. export let loader: LoaderFunction = async ({ params }) => {
  6.   return db.product.findMany({
  7.     where: {
  8.       categoryId: params.categoryId
  9.     }
  10.   });
  11. };
  13. export default function ProductCategory() {
  14.   let products = useLoaderData();
  15.   return (
  16.     <div>
  17.       <p>{products.length} Products</p>
  18.       {/* ... */}
  19.     </div>
  20.   );
  21. }

Cloudflare KV

If you picked Cloudflare Workers as you environment, Cloudflare Key Value storage allows you to persist data at the edge as if it were a static resource. You’ll need to do some configuration but then you can access the data from your loaders:

  1. import { useLoaderData } from "remix";
  2. import type { LoaderFunction } from "remix";
  4. export let loader: LoaderFunction = async ({ params }) => {
  5.   return PRODUCTS_KV.get(`product-${params.productId}`, {
  6.     type: "json"
  7.   });
  8. };
  10. export default function Product() {
  11.   let product = useLoaderData();
  12.   return (
  13.     <div>
  14.       <p>{} Products</p>
  15.       {/* ... */}
  16.     </div>
  17.   );
  18. }

Not Found

While loading data its common for a record to be “not found”. As soon as you know you can’t render the component as expected, throw a response and Remix will stop executing code in the current loader and switch over to the nearest catch boundary.

  1. export let loader: LoaderFunction = async ({
  2.   params,
  3.   request
  4. }) => {
  5.   let product = await db.product.findOne({
  6.     where: { id: params.productId }
  7.   });
  9.   if (!product) {
  10.     // we know we can't render the component
  11.     // so throw immediately to stop executing code
  12.     // and show the not found page
  13.     throw new Response("Not Found", { status: 404 });
  14.   }
  16.   let cart = await getCart(request);
  17.   return { product, inCart: cart.includes(product.id) };
  18. };

URL Search Params

URL Search Params are the portion of the URL after a ?. Other names for this are “query string”, “search string”, or “location search”. You can access the values by creating a URL out of the request.url:

  1. import type { LoaderFunction } from "remix";
  3. export let loader: LoaderFunction = ({ request }) => {
  4.   let url = new URL(request.url);
  5.   let term = url.searchParams.get("term");
  6.   return fakeProductSearch(term);
  7. };

There are a few web platform types at play here:

  • The request object has a url property
  • URL constructor that parses the URL string into an object
  • url.searchParams is an instance of URLSearchParams, which is a parsed version of the location search string that makes it easy to read and manipulate the search string

Given the following URLs, the search params would be parsed as follows:

URLurl.searchParams.get(“term”)
/products?term=stretchy+pants“stretchy pants”
/products?term=“”
/productsnull

Data Reloads

When multiple nested routes are rendering and the search params change, all of the routes will be reloaded (instead of just the new or changed routes). This is because search params are a cross-cutting concern and could effect any loader. If you would like to prevent some of your routes from reloading in this scenario, use shouldReload.

Search Params in Components

Sometimes you need to read and change the search params from your component instead of your loaders and actions. There are handful of ways to do this depending on your use case.

Setting Search Params

Perhaps the most common way to set search params is letting the user control them with a form:

  1. export default function ProductFilters() {
  2.   return (
  3.     <Form method="get">
  4.       <label htmlFor="nike">Nike</label>
  5.       <input
  6.         type="checkbox"
  7.         id="nike"
  8.         name="brand"
  9.         value="nike"
  10.       />
  12.       <label htmlFor="adidas">Adidas</label>
  13.       <input
  14.         type="checkbox"
  15.         id="adidas"
  16.         name="brand"
  17.         value="adidas"
  18.       />
  20.       <button type="submit">Update</button>
  21.     </Form>
  22.   );
  23. }

If the user only has one selected:

  • Nike
  • Adidas

Then the URL will be /products/shoes?brand=nike

If the user has both selected:

  • Nike
  • Adidas

Then the url will be: /products/shoes?brand=nike&brand=adidas

Note that brand is repeated in the URL search string since both checkboxes were named "brand". In your loader you can get access to all of those values with searchParams.getAll

  1. export function loader({ request }) {
  2.   let url = new URL(request.url);
  3.   let brands = url.searchParams.getAll("brand");
  4.   return getProducts({ brands });
  5. }

Linking to Search Params

As the developer, you can control the search params by linking to URLs with search strings in them. The link will replace the current search string in the URL (if there is one) with what is in the link:

  1. <Link to="?brand=nike">Nike (only)</Link>

Reading Search Params in Components

In addition to reading search params in loaders, you often need access to them in components, too:

  1. import { useSearchParams } from "remix";
  3. export default function ProductFilters() {
  4.   let [searchParams] = useSearchParams();
  5.   let brands = searchParams.getAll("brand");
  7.   return (
  8.     <Form method="get">
  9.       <label htmlFor="nike">Nike</label>
  10.       <input
  11.         type="checkbox"
  12.         id="nike"
  13.         name="brand"
  14.         value="nike"
  15.         defaultChecked={brands.includes("nike")}
  16.       />
  18.       <label htmlFor="adidas">Adidas</label>
  19.       <input
  20.         type="checkbox"
  21.         id="adidas"
  22.         name="brand"
  23.         value="adidas"
  24.         defaultChecked={brands.includes("nike")}
  25.       />
  27.       <button type="submit">Update</button>
  28.     </Form>
  29.   );
  30. }

You might want to auto submit the form on any field change, for that there is useSubmit:

  1. import { useSubmit, useSearchParams } from "remix";
  3. export default function ProductFilters() {
  4.   let submit = useSubmit();
  5.   let [searchParams] = useSearchParams();
  6.   let brands = searchParams.getAll("brand");
  8.   return (
  9.     <Form method="get" onChange={e => submit(e.target)}>
  10.       {/* ... */}
  11.     </Form>
  12.   );
  13. }

Setting Search Params Imperatively

While uncommon, you can also set searchParams imperatively at any time for any reason. The use cases here are slim, so slim we couldn’t even come up with a good one, but here’s a silly example:

  1. import { useSearchParams } from "remix";
  3. export default function ProductFilters() {
  4.   let [searchParams, setSearchParams] = useSearchParams();
  6.   useEffect(() => {
  7.     let id = setInterval(() => {
  8.       setSearchParams({ now: Date.now() });
  9.     }, 1000);
  10.     return () => clearInterval(id);
  11.   }, [setSearchParams]);
  13.   // ...
  14. }

Search Params and Controlled Inputs

Often you want to keep some inputs, like checkboxes, in sync with the search params in the URL. This can get a little tricky with React’s controlled component concept.

This is only needed if the search params can be set in two ways and we want the inputs to stay in sync with the search params. For example, both the <input type="checkbox"> and the Link can change the brand in this component:

  1. import { useSearchParams } from "remix";
  3. export default function ProductFilters() {
  4.   let [searchParams] = useSearchParams();
  5.   let brands = searchParams.getAll("brand");
  7.   return (
  8.     <Form method="get">
  9.       <p>
  10.         <label htmlFor="nike">Nike</label>
  11.         <input
  12.           type="checkbox"
  13.           id="nike"
  14.           name="brand"
  15.           value="nike"
  16.           defaultChecked={brands.includes("nike")}
  17.         />
  18.         <Link to="?brand=nike">(only)</Link>
  19.       </p>
  21.       <button type="submit">Update</button>
  22.     </Form>
  23.   );
  24. }

If the user clicks the checkbox and submits the form, the URL updates and the checkbox state changes too. But if the user clicks the link only the url will update and not the checkbox. That’s not what we want. You may be familiar with React’s controlled components here and think to switch it to checked instead of defaultChecked:

  1. <input
  2.   type="checkbox"
  3.   id="adidas"
  4.   name="brand"
  5.   value="adidas"
  6.   checked={brands.includes("adidas")}
  7. />

Now we have the opposite problem: clicking the link updates both the URL and the checkbox state but the checkbox no longer works because React prevents the state from changing until the URL that controls it changes—and it never will because we can’t change the checkbox and resubmit the form.

React wants you to control it with some state but we want the user to control it until they submit the form, and then we want the URL to control it when it changes. So we’re in this “sorta-controlled” spot.

You have two choices, and what you pick depends on the user experience you want.

First Choice: The simplest thing is to auto-submit the form when the user clicks the checkbox:

  1. import { useSubmit, useSearchParams } from "remix";
  3. export default function ProductFilters() {
  4.   let submit = useSubmit();
  5.   let [searchParams] = useSearchParams();
  6.   let brands = searchParams.getAll("brand");
  8.   return (
  9.     <Form method="get">
  10.       <p>
  11.         <label htmlFor="nike">Nike</label>
  12.         <input
  13.           type="checkbox"
  14.           id="nike"
  15.           name="brand"
  16.           value="nike"
  17.           onChange={e => submit(e.currentTarget.form)}
  18.           checked={brands.includes("nike")}
  19.         />
  20.         <Link to="?brand=nike">(only)</Link>
  21.       </p>
  23.       {/* ... */}
  24.     </Form>
  25.   );
  26. }

(If you are also auto submitting on the form onChange, make sure to e.stopPropagation() so the event doesn’t bubble up to the form, otherwise you’ll get double submissions on every click of the checkbox.)

Second Choice: If you want the input to be “semi controlled”, where the checkbox reflects the URL state, but the user can also toggle it on and off before submitting the form and changing the URL, you’ll need to wire up some state. It’s a bit of work but straightforward:

  • Initialize some state from the search params
  • Update the state when the user clicks the checkbox so the box changes to “checked”
  • Update the state when the search params change (the user submitted the form or clicked the link) to reflect what’s in the url search params
  1. import { useSubmit, useSearchParams } from "remix";
  3. export default function ProductFilters() {
  4.   let submit = useSubmit();
  5.   let [searchParams] = useSearchParams();
  6.   let brands = searchParams.getAll("brand");
  8.   let [nikeChecked, setNikeChecked] = React.useState(
  9.     // initialize from the URL
  10.     brands.includes("nike")
  11.   );
  13.   // Update the state when the params change
  14.   // (form submission or link click)
  15.   React.useEffect(() => {
  16.     setNikeChecked(brands.includes("nike"));
  17.   }, [searchParams]);
  19.   return (
  20.     <Form method="get">
  21.       <p>
  22.         <label htmlFor="nike">Nike</label>
  23.         <input
  24.           type="checkbox"
  25.           id="nike"
  26.           name="brand"
  27.           value="nike"
  28.           onChange={e => {
  29.             // update checkbox state w/o submitting the form
  30.             setNikeChecked(true);
  31.           }}
  32.           checked={nikeChecked}
  33.         />
  34.         <Link to="?brand=nike">(only)</Link>
  35.       </p>
  37.       {/* ... */}
  38.     </Form>
  39.   );
  40. }

You might want to make an abstraction for checkboxes like this:

  1. <div>
  2.   <SearchCheckbox name="brand" value="nike" />
  3.   <SearchCheckbox name="brand" value="reebok" />
  4.   <SearchCheckbox name="brand" value="adidas" />
  5. </div>;
  7. function SearchCheckbox({ name, value }) {
  8.   let [searchParams] = useSearchParams();
  9.   let all = searchParams.getAll(name);
  10.   let [checked, setChecked] = React.useState(
  11.     all.includes(value)
  12.   );
  14.   React.useEffect(() => {
  15.     setChecked(all.includes(value));
  16.   }, [searchParams]);
  18.   return (
  19.     <input
  20.       type="checkbox"
  21.       name={name}
  22.       value={value}
  23.       checked={checked}
  24.       onChange={e => setChecked(e.target.checked)}
  25.     />
  26.   );
  27. }

Option 3: We said there were only two options, but there is a third unholy option that might tempt you if you know React pretty well. You might want to blow away the input and remount it with key prop shenanigans. While clever, this will cause accessibility issues as the user will lose focus when React removes the node from the document after they click it.

Don’t do this, it will cause accessibility issues

  1. <input
  2.   type="checkbox"
  3.   id="adidas"
  4.   name="brand"
  5.   value="adidas"
  6.   key={"adidas" + brands.includes("adidas")}
  7.   defaultChecked={brands.includes("adidas")}
  8. />

Remix Optimizations

Remix optimizes the user experiences by only loading the data for the parts of the page that are changing on navigation. For example, consider the UI you’re using right now in these docs. The navbar on the side is in a parent route that fetched the dynamically generated menu of all the docs, and the child route fetched the document you’re reading right now. If you click a link in the sidebar Remix knows that the parent route will remain on the page but the child route’s data will change because the url param for the document will change. With this insight, Remix will not refetch the parent route’s data.

Without Remix the next question is “how do I reload all of the data?”. This is built into Remix as well. Whenever an action is called (the user submitted a form or you, the programmer, called submit from useSubmit), Remix will automatically reload all of the routes on the page to capture any changes that might have happened.

You don’t have to worry about expiring caches or avoid overfetching data as the user interacts with your app, it’s all automatic.

There are three cases where Remix will reload all of your routes:

  • After an action (forms, useSubmit, fetcher.submit)
  • If the url search params change (any loader could use them)
  • The user clicks a link to the exact same URL they are already at (this will also replace the current entry in the history stack)

All of these behaviors emulate the browser’s default behavior. In these cases, Remix doesn’t know enough about your code to optimize the data loading, but you can optimize it yourself with unstable_shouldReload.

Data Libraries

Thanks to Remix’s data conventions and nested routes, you’ll usually find you don’t need to reach for client side data libraries like React Query, SWR, Apollo, Relay, urql and others. If you’re using global state management libraries like redux, primarily for interacting with data on the server, it’s also unlikely you’ll need those.

Of course, Remix doesn’t prevent you from using them (unless they require bundler integration). You can bring whatever React data libraries you like and use them wherever you think they’ll serve your UI better than the Remix APIs. In some cases you can use Remix for the initial server render and then switch over to your favorite library for the interactions afterward.

That said, if you bring an external data library and sidestep Remix’s own data conventions, Remix can no longer automatically

  • Server render your pages
  • Be resilient to network conditions when JavaScript fails to load
  • Make optimizations as the user interacts with your site to make it fast by only loading data for the changing parts of the page
  • Fetch data, JavaScript modules, CSS and other assets in parallel on transitions, avoiding render+fetch waterfalls that lead to choppy UI
  • Ensure the data in the UI is in sync with the data on the server by revalidating after actions
  • Excellent scroll restoration on back/forward clicks (even across domains)
  • Handle server side errors with error boundaries
  • Enable solid UX for “Not Found” and “Unauthorized” with catch boundaries
  • Help you keep the happy path of your UI happy.

Instead you’ll need to do extra work to provide a good user experience.

Remix is designed to meet any user experience you can design. While it’s unexpected that you need an external data library, you might still want one and that’s fine!

As you learn Remix, you’ll find you shift from thinking in client state to thinking in URLs, and you’ll get a bunch of stuff for free when you do.

Gotchas

Loaders are only called on the server, via fetch from the browser, so your data is serialized with JSON.stringify and sent over the network before it makes it to you component. This means your data needs to be serializable. For example:

This won’t work!

  1. export function loader() {
  2.   return {
  3.     date: new Date(),
  4.     someMethod() {
  5.       return "hello!";
  6.     }
  7.   };
  8. }
  10. export default function RouteComp() {
  11.   let data = useLoaderData();
  12.   console.log(data);
  13.   // '{"date":"2021-11-27T23:54:26.384Z"}'
  14. }

Not everything makes it! Loaders are for data, and data needs to be serializable.

Some databases (like FaunaDB) return objects with methods that you’ll want to be careful to serialize before returning from your loader. Usually this isn’t a problem, but it’s good to understand that your data is traveling over the network.

Additionally, Remix will call your loaders for you, in no case should you ever try to call your loader directly:

This will not work

  1. export let loader = async () => {
  2.   return fakeDb.products.findMany();
  3. };
  5. export default function RouteComp() {
  6.   let data = loader();
  7.   // ...
  8. }