Styling

The primary way to style in Remix (and the web) is to add a <link rel="stylesheet"> to the page. In Remix, you can add these links at route layout boundaries. When the route is active, the stylesheet is added to the page. When the route is no longer active, the stylesheet is removed.

  1. export function links() {
  2.   return [
  3.     {
  4.       rel: "stylesheet",
  5.       href: "https://unpkg.com/modern-css-reset@1.4.0/dist/reset.min.css"
  6.     }
  7.   ];
  8. }

Each nested route’s links are merged (parents first) and rendered as <link> tags by the <Links/> you rendered in app/root.js in the head of the document.

  1. import { Links } from "remix";
  2. // ...
  3. export default function Root() {
  4.   return (
  5.     <html>
  6.       <head>
  7.         <Links />
  8.         {/* ... */}
  9.       </head>
  10.       {/* ... */}
  11.     </html>
  12.   );
  13. }

You can also import CSS files directly into your modules and Remix will:

  1. Copy the file to your browser build directory
  2. Fingerprint the file for long-term caching
  3. Return the public URL to your module to be used while rendering
  1. // ...
  2. import styles from "~/styles/global.css";
  3. // styles is now something like /build/global-AE33KB2.css
  5. export function links() {
  6.   return [{ rel: "stylesheet", href: styles }];
  7. }

CSS Ecosystem and Performance

We are still researching how best to support, and be supported by, the various styling libraries without sacrificing the user’s network tab or creating a maintenance burden for Remix.

In today’s ecosystem there are dozens of approaches and frameworks for styling. Remix supports many of them out of the box, but the frameworks that require direct integration with our compiler and expect Remix to automatically inject styles onto the page don’t work right now.

We recognize that not being able to use your favorite CSS framework is a bummer. If yours isn’t supported right now, we hope you’ll find some of the approaches in this document equally as productive. We also recognize that supporting a variety of tools is critical for migration paths to Remix.

Here’s some background on where we’re at.

In general, stylesheets added to the page with <link> tend to provide the best user experience:

  • The URL is cacheable in browsers and CDNs
  • The URL can be shared across pages in the app
  • The stylesheet can be loaded in parallel with the JavaScript bundles
  • Remix can prefetch CSS assets when the user is about to visit a page with <Link rel="prefetch">.
  • Changes to components don’t break the cache for the styles
  • Changes to the styles don’t break the cache for the JavaScript

Therefore, CSS support in Remix boils down to one thing: it needs to create a CSS file you can add to the page with <link rel="stylesheet">. This seems like a reasonable request of a CSS framework—to generate a CSS file. Remix isn’t against the frameworks that can’t do this, it’s just too early for us to add extension points to the compiler. Aditionally, adding support directly inside of Remix is not tenable with the vast number of libraries out there.

Remix also supports “runtime” frameworks like styled components where styles are evaluated at runtime but don’t require any kind of bundler integration—though we would prefer your stylesheets had a URL instead of being injected into style tags.

All this is to say that we’re still researching how best to integrate and work with the frameworks that require compiler integration. With Remix’s unique ability to prefetch, add, and remove CSS for partial UI on the page, we anticipate CSS frameworks will have some new ideas on how to support building actual CSS files to better support Remix and the performance of websites using them.

The two most popular approaches in the Remix community are route-based stylesheets and Tailwind. Both have exceptional performance characteristics. In this document we’ll show how to use these two approaches as well as a few more.

Regular Stylesheets

Remix makes writing plain CSS a viable option even for apps with a lot of UI. In our experience, writing plain CSS had maintenence issues for a few reasons. It was difficult to know:

  • how and when to load CSS, so it was usually all loaded on every page
  • if the class names and selectors you were using were accidentally styling other UI in the app
  • if some rules were even used anymore as the css source code grew over time

Remix alleviates these issues with route-based stylesheets. Nested routes can each add their own stylesheets to the page and Remix will automatically prefetch, load, and unload them with the route. When the scope of concern is limited to just the active routes, the risks of these problems are reduced significantly. The only chances for conflicts are with the parent routes’ styles (and even then, you will likely see the conflict since the parent route is also rendering).

Route Styles

Each route can add style links to the page, for example:

  1. import styles from "~/styles/dashboard.css";
  3. export function links() {
  4.   return [{ rel: stylesheet, href: styles }];
  5. }
  1. import styles from "~/styles/accounts.css";
  3. export function links() {
  4.   return [{ rel: stylesheet, href: styles }];
  5. }
  1. import styles from "~/styles/sales.css";
  3. export function links() {
  4.   return [{ rel: stylesheet, href: styles }];
  5. }

Given these routes, this table shows which CSS will apply at specific URLs:

URLStylesheets
/dashboard- dashboard.css
/dashboard/accounts- dashboard.css
- accounts.css
/dashboard/sales- dashboard.css
- sales.css

It’s subtle, but this little feature removes a lot of the difficulty when styling your app with plain stylesheets.

Shared Component Styles

Websites large and small usually have a set of shared components used throughout the rest of the app: buttons, form elements, layouts, etc. When using plain style sheets in Remix there are two approaches we recommend.

Shared stylesheet

The first is approach is very simple. Put them all in a shared.css file included in app/root.tsx. That makes it easy for the components themselves to share CSS code (and your editor to provide intellisense for things like custom properties), and each component already needs a unique module name in JavaScript anyway, so you can scope the styles to a unique class name or data attribute:

  1. /* scope with class names */
  2. .PrimaryButton {
  3.   /* ... */
  4. }
  6. .TileGrid {
  7.   /* ... */
  8. }
  10. /* or scope with data attributes to avoid concatenating
  11.    className props, but it's really up to you */
  12. [data-primary-button] {
  13.   /* ... */
  14. }
  16. [data-tile-grid] {
  17.   /* ... */
  18. }

While this file may become large, it’ll be at a single URL that will be shared by all routes in the app.

This also makes it easy for routes to adjust the styles of a component without needing to add an official new variant to the API of that component. You know it won’t affect the component anywhere but the /accounts routes.

  1. .PrimaryButton {
  2.   background: blue;
  3. }

Surfacing Styles

A second approach is to write individual css files per component and then “surface” the styles up to the routes that use them.

Perhaps you have a <Button> in app/components/button/index.js with styles at app/components/button/styles.css as well as a <PrimaryButton> that extends it.

Note that these are not routes, but they export links functions as if they were. We’ll use this to surface their styles to the routes that use them.

  1. [data-button] {
  2.   border: solid 1px;
  3.   background: white;
  4.   color: #454545;
  5. }
  1. import styles from "./styles.css";
  3. export const links = () => [
  4.   { rel: "stylesheet", href: styles }
  5. ];
  7. export const Button = React.forwardRef(
  8.   ({ children, ...props }, ref) => {
  9.     return <button {...props} ref={ref} data-button />;
  10.   }
  11. );

And then a <PrimaryButton> that extends it:

  1. [data-primary-button] {
  2.   background: blue;
  3.   color: white;
  4. }
  1. import { Button, links as buttonLinks } from "../button";
  2. import styles from "./styles.css";
  4. export const links = () => [
  5.   ...buttonLinks(),
  6.   { rel: "stylesheet", href: styles }
  7. ];
  9. export const PrimaryButton = React.forwardRef(
  10.   ({ children, ...props }, ref) => {
  11.     return (
  12.       <Button {...props} ref={ref} data-primary-button />
  13.     );
  14.   }
  15. );

Note that the primary button’s links include the base button’s links. This way consumers of <PrimaryButton> don’t need to know it’s dependencies (just like JavaScript imports).

Because these buttons are not routes, and therefore not associate with a URL segment, Remix doesn’t know when to prefetch, load, or unload the styles. We need to “surface” the links up to the routes that use the components.

Consider that routes/index.js uses the primary button component:

  1. import styles from "~/styles/index.css";
  2. import {
  3.   PrimaryButton,
  4.   links as primaryButtonLinks
  5. } from "~/components/primary-button";
  7. export function links() {
  8.   return [
  9.     ...primaryButtonLinks(),
  10.     { rel: "stylesheet", href: styles }
  11.   ];
  12. }

Now Remix can prefetch, load, and unload the styles for button.css, primary-button.css, and the route’s index.css.

An initial reaction to this is that routes have to know more than you want them to. Keep in mind each component must be imported already, so its not introducing a new dependency, just some boilerplate to get the assets. For example, consider a product category page like this:

  1. import { TileGrid } from "~/components/tile-grid";
  2. import { ProductTile } from "~/components/product-tile";
  3. import { ProductDetails} from "~/components/product-details";
  4. import { AddFavoriteButton } from "~/components/add-favorite-button";
  6. import styles from "~/styles/$category.css";
  8. export function links() {
  9.   return [{ rel: "stylesheet", href: styles }];
  10. }
  12. export function loader({ params }) {
  13.   return getProductsForCategory(params.category);
  14. }
  16. export default function Category() {
  17.   const products = useLoaderData();
  18.   return (
  19.     <TileGrid>
  20.       {products.map(product => (
  21.         <ProductTile key={product.id}>
  22.           <ProductDetails product={product} />
  23.           <AddFavoriteButton id={product.id}>
  24.         </ProductTile>
  25.       ))}
  26.     </TileGrid>
  27.   );
  28. }

The component imports are already there, we just need to surface the assets:

  1. import {
  2.   TileGrid,
  3.   links as tileGridLinks
  4. } from "~/components/tile-grid";
  5. import {
  6.   ProductTile,
  7.   links as productTileLinks
  8. } from "~/components/product-tile";
  9. import {
  10.   ProductDetails,
  11.   links as productDetailsLinks
  12. } from "~/components/product-details";
  13. import {
  14.   AddFavoriteButton,
  15.   links as addFavoriteLinks
  16. } from "~/components/add-favorite-button";
  18. import styles from "~/styles/$category.css";
  20. export function links() {
  21.   return [
  22.     ...tileGridLinks(),
  23.     ...productTileLinks(),
  24.     ...productDetailsLinks(),
  25.     ...addFavoriteLinks(),
  26.     { rel: "stylesheet", href: styles }
  27.   ];
  28. }
  30. // ...

While that’s a bit of boilerplate it enables a lot:

  • You control your network tab, and CSS dependencies are clear in the code
  • Co-located styles with your components
  • The only CSS ever loaded is the CSS that’s used on the current page
  • When your components aren’t used by a route, their CSS is unloaded from the page
  • Remix will prefetch the CSS for the next page with
  • When one compoenent’s styles change, browser and CDN caches for the other components won’t break because they are all have their own URLs.
  • When a component’s JavaScript changes but it’s styles don’t, the cache is not broken for the styles

Asset Preloads

Since these are just <link> tags, you can do more than stylesheet links, like adding asset preloads for SVG icon backgrounds of your elements:

  1. [data-copy-to-clipboard] {
  2.   background: url("/icons/clipboard.svg");
  3. }
  1. import styles from "./styles.css";
  3. export const links = () => [
  4.   {
  5.     rel: "preload",
  6.     href: "/icons/clipboard.svg",
  7.     as: "image",
  8.     type: "image/svg+xml"
  9.   },
  10.   { rel: "stylesheet", href: styles }
  11. ];
  13. export const CopyToClipboard = React.forwardRef(
  14.   ({ children, ...props }, ref) => {
  15.     return (
  16.       <Button {...props} ref={ref} data-copy-to-clipboard />
  17.     );
  18.   }
  19. );

Not only will this make the asset high priority in the network tab, but Remix will turn that preload into a prefetch when you link to the page with , so the SVG background is prefetched, in parallel, with the next route’s data, modules, stylesheets, and any other preloads.

Using plain stylesheets and <link> tags also opens up the ability to decrease the amount of CSS your user’s browser has to process when it paints the screen. Link tags support media, so you you can do the following:

  1. export function links() {
  2.   return [
  3.     {
  4.       rel: "stylesheet",
  5.       href: mainStyles
  6.     },
  7.     {
  8.       rel: "stylesheet",
  9.       href: largeStyles,
  10.       media: "(min-width: 1024px)"
  11.     },
  12.     {
  13.       rel: "stylesheet",
  14.       href: xlStyles,
  15.       media: "(min-width: 1280px)"
  16.     },
  17.     {
  18.       rel: "stylesheet",
  19.       href: darkStyles,
  20.       media: "(prefers-color-scheme: dark)"
  21.     }
  22.   ];
  23. }

Tailwind

Perhaps the most popular way to style a Remix application in the community is to use tailwind. It has the benefits of inline-style colocation for developer ergonomics and is able to generate a CSS file for Remix to import. The generated CSS file generally caps out around 8-10kb, even for large applications. Load that file into the root.tsx links and be done with it. If you don’t have any CSS opinions, this is a great approach.

First install a couple dev dependencies:

  1. npm add -D concurrently tailwindcss

Initialize a tailwind config so we can tell it which files to generate classes from.

  1. module.exports = {
  2.   mode: "jit",
  3.   purge: ["./app/**/*.{ts,tsx}"],
  4.   darkMode: "media", // or 'media' or 'class'
  5.   theme: {
  6.     extend: {}
  7.   },
  8.   variants: {},
  9.   plugins: []
  10. };

Update the package scripts to generate the tailwind file during dev and for the production build

  1. {
  2.   // ...
  3.   "scripts": {
  4.     "build": "npm run build:css && remix build",
  5.     "build:css": "tailwindcss -o ./app/tailwind.css",
  6.     "dev": "concurrently \"npm run dev:css\" \"remix dev\"",
  7.     "dev:css": "tailwindcss -o ./app/tailwind.css --watch",
  8.     "postinstall": "remix setup node",
  9.     "start": "remix-serve build"
  10.   }
  11.   // ...
  12. }

Finally, import the generated CSS file into your app:

  1. // ...
  2. import styles from "./tailwind.css";
  4. export function links() {
  5.   return [{ rel: "stylesheet", href: styles }];
  6. }

This isn’t required, but it’s recommended to add the generated file to your gitignore list:

  1. node_modules
  2. /.cache
  3. /build
  4. /public/build
  5. /app/tailwind.css

If you’re using VSCode, it’s recommended you install the tailwind intellisense extension for the best developer experience.

Remote Stylesheets

You can load stylesheets from any server, here’s an example of loading a modern css reset from unpkg.

  1. import type { LinksFunction } from "remix";
  3. export const links: LinksFunction = () => {
  4.   return [
  5.     {
  6.       rel: "stylesheet",
  7.       href: "https://unpkg.com/modern-css-reset@1.4.0/dist/reset.min.css"
  8.     }
  9.   ];
  10. };

PostCSS

While not built into Remix’s compiler, it is straight forward to use PostCSS and add whatever syntax sugar you’d like to your stylesheets, here’s the gist of it:

  1. Use postcss cli directly alongside Remix
  2. Build CSS into the Remix app directory from a styles source directory
  3. Import your stylesheet to your modules like any other stylesheet

Here’s how to set it up:

  1. Install the dev dependencies in your app:

    1. npm install -D postcss-cli postcss autoprefixer

  2. Add postcss.config.js in the Remix root.

    1. module.exports = {
    2.   plugins: {
    3.     autoprefixer: {}
    4.   }
    5. };

  3. Add stylesheets to a styles/ folder next to app/, we’ll point postcss at this folder to build into the app/styles folder next.

    1. mkdir styles
    2. touch styles/app.css

  4. Add some scripts to your package.json

    1. {
    2.   "scripts": {
    3.     "dev:css": "postcss styles --base styles --dir app/styles -w",
    4.     "build:css": "postcss styles --base styles --dir app/styles --env production"
    5.   }
    6. }

    These commands will process files from ./styles into ./app/styles where your Remix modules can import them.

    1. .
    2. ├── app
    3. │   └── styles (processed files)
    4. │       ├── app.css
    5. │       └── routes
    6. │           └── index.css
    7. └── styles (source files)
    8.     ├── app.css
    9.     └── routes
    10.         └── index.css

    We recommend adding app/styles to your .gitignore.

  5. Use it! When you’re developing styles, open a terminal tab and run your new watch script:

    1. npm run dev:css

    When you’re building for production, run

    1. npm run build:css

    Then import like any other css file:

    1. import type { LinksFunction } from "remix";
    2. import styles from "./styles/app.css";
    4. export const links: LinksFunction = () => {
    5.   return [{ rel: "stylesheet", href: styles }];
    6. };

You might want to use something like concurrently to avoid needing two terminal tabs to watch your CSS and run remix dev.

  1. npm add -D concurrently
  1. {
  2.   "scripts": {
  3.     "dev": "concurrently \"npm run dev:css\" \"remix dev\""
  4.   }
  5. }

CSS-in-JS libraries

You can use CSS-in-JS libraries like Styled Components. Some of them require a “double render” in order to extract the styles from the component tree during the server render. It’s unlikely this will effect performance in a significant way, React is pretty fast.

Here’s some sample code to show how you might use Styled Components with Remix:

  1. First you’ll need some context to put your styles on so that your root route can render them.

    1. // app/StylesContext.tsx
    2. import { createContext } from "react";
    3. export default createContext<null | string>(null);

  2. Your entry.server.tsx will look something like this:

    1. // app/entry.server.tsx
    2. import ReactDOMServer from "react-dom/server";
    3. import type { EntryContext } from "remix";
    4. import { RemixServer } from "remix";
    5. import { renderToString } from "react-dom/server";
    6. import { ServerStyleSheet } from "styled-components";
    7. import StylesContext from "./StylesContext";
    9. export default function handleRequest(
    10.   request: Request,
    11.   responseStatusCode: number,
    12.   responseHeaders: Headers,
    13.   remixContext: EntryContext
    14. ) {
    15.   // set up the Styled Components sheet
    16.   const sheet = new ServerStyleSheet();
    18.   // This render is thrown away, it's here simply to let styled components
    19.   // extract the styles used
    20.   renderToString(
    21.     sheet.collectStyles(
    22.       <StylesContext.Provider value={null}>
    23.         <RemixServer
    24.           context={remixContext}
    25.           url={request.url}
    26.         />
    27.       </StylesContext.Provider>
    28.     )
    29.   );
    31.   // Now that we've rendered, we get the styles out of the sheet
    32.   const styles = sheet.getStyleTags();
    33.   sheet.seal();
    35.   // Finally, we render a second time, but this time we have styles to apply,
    36.   // make sure to pass them to `<StylesContext.Provider value>`
    37.   const markup = ReactDOMServer.renderToString(
    38.     <StylesContext.Provider value={styles}>
    39.       <RemixServer
    40.         context={remixContext}
    41.         url={request.url}
    42.       />
    43.     </StylesContext.Provider>
    44.   );
    46.   responseHeaders.set("Content-Type", "text/html");
    48.   return new Response("<!DOCTYPE html>" + markup, {
    49.     status: responseStatusCode,
    50.     headers: responseHeaders
    51.   });
    52. }

  3. Finally, access and render the styles in your root route.

    1. // app/root.tsx
    2. import { Meta, Scripts } from "remix";
    3. import { useContext } from "react";
    4. import StylesContext from "./StylesContext";
    6. export default function Root() {
    7.   const styles = useContext(StylesContext);
    9.   return (
    10.     <html>
    11.       <head>
    12.         <Meta />
    13.         {styles}
    14.       </head>
    15.       <body>
    16.         <Scripts />
    17.       </body>
    18.     </html>
    19.   );
    20. }

Other CSS-in-JS libraries will have a similar setup. If you’ve got a CSS framework working well with Remix, please create a GitHub repo and add a link to it in this document!