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 via the Route Module links export 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 const links: LinksFunction = () => {
  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-run/react";
  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. }

Remix also has built-in support for the following:

CSS Ecosystem and Performance

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

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.

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 maintenance 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 weren’t 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 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. );
  12. Button.displayName = "Button";

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";
  3. import styles from "./styles.css";
  5. export const links = () => [
  6.   ...buttonLinks(),
  7.   { rel: "stylesheet", href: styles },
  8. ];
  10. export const PrimaryButton = React.forwardRef(
  11.   ({ children, ...props }, ref) => {
  12.     return (
  13.       <Button {...props} ref={ref} data-primary-button />
  14.     );
  15.   }
  16. );
  17. PrimaryButton.displayName = "PrimaryButton";

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

Because these buttons are not routes, and therefore not associated 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 {
  2.   PrimaryButton,
  3.   links as primaryButtonLinks,
  4. } from "~/components/primary-button";
  5. import styles from "~/styles/index.css";
  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 that each component must be imported already, so it’s not introducing a new dependency, just some boilerplate to get the assets. For example, consider a product category page like this:

  1. import type { LoaderArgs } from "@remix-run/node"; // or cloudflare/deno
  2. import { json } from "@remix-run/node"; // or cloudflare/deno
  3. import { useLoaderData } from "@remix-run/react";
  5. import { AddFavoriteButton } from "~/components/add-favorite-button";
  6. import { ProductDetails } from "~/components/product-details";
  7. import { ProductTile } from "~/components/product-tile";
  8. import { TileGrid } from "~/components/tile-grid";
  9. import styles from "~/styles/$category.css";
  11. export function links() {
  12.   return [{ rel: "stylesheet", href: styles }];
  13. }
  15. export async function loader({ params }: LoaderArgs) {
  16.   return json(
  17.     await getProductsForCategory(params.category)
  18.   );
  19. }
  21. export default function Category() {
  22.   const products = useLoaderData<typeof loader>();
  23.   return (
  24.     <TileGrid>
  25.       {products.map((product) => (
  26.         <ProductTile key={product.id}>
  27.           <ProductDetails product={product} />
  28.           <AddFavoriteButton id={product.id} />
  29.         </ProductTile>
  30.       ))}
  31.     </TileGrid>
  32.   );
  33. }

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

  1. import type { LinksFunction } from "@remix-run/node"; // or cloudflare/deno
  3. import {
  4.   AddFavoriteButton,
  5.   links as addFavoriteLinks,
  6. } from "~/components/add-favorite-button";
  7. import {
  8.   ProductDetails,
  9.   links as productDetailsLinks,
  10. } from "~/components/product-details";
  11. import {
  12.   ProductTile,
  13.   links as productTileLinks,
  14. } from "~/components/product-tile";
  15. import {
  16.   TileGrid,
  17.   links as tileGridLinks,
  18. } from "~/components/tile-grid";
  19. import styles from "~/styles/$category.css";
  21. export const links: LinksFunction = () => {
  22.   return [
  23.     ...tileGridLinks(),
  24.     ...productTileLinks(),
  25.     ...productDetailsLinks(),
  26.     ...addFavoriteLinks(),
  27.     { rel: "stylesheet", href: styles },
  28.   ];
  29. };
  31. // ...

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 component’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 its 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 type { LinksFunction } from "@remix-run/node"; // or cloudflare/deno
  3. import styles from "./styles.css";
  5. export const links: LinksFunction = () => [
  6.   {
  7.     rel: "preload",
  8.     href: "/icons/clipboard.svg",
  9.     as: "image",
  10.     type: "image/svg+xml",
  11.   },
  12.   { rel: "stylesheet", href: styles },
  13. ];
  15. export const CopyToClipboard = React.forwardRef(
  16.   ({ children, ...props }, ref) => {
  17.     return (
  18.       <Button {...props} ref={ref} data-copy-to-clipboard />
  19.     );
  20.   }
  21. );
  22. CopyToClipboard.displayName = "CopyToClipboard";

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 can do the following:

  1. export const links: LinksFunction = () => {
  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 CSS

Perhaps the most popular way to style a Remix application in the community is to use Tailwind CSS. It has the benefits of inline-style collocation 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.

To use the built-in Tailwind support, first enable the tailwind option in remix.config.js:

  1. /** @type {import('@remix-run/dev').AppConfig} */
  2. module.exports = {
  3.   tailwind: true,
  4.   // ...
  5. };

Install Tailwind as a dev dependency:

  1. npm install -D tailwindcss

Then initialize a config file:

  1. npx tailwindcss init --ts

Now we can tell it which files to generate classes from:

  1. import type { Config } from "tailwindcss";
  3. export default {
  4.   content: ["./app/**/*.{js,jsx,ts,tsx}"],
  5.   theme: {
  6.     extend: {},
  7.   },
  8.   plugins: [],
  9. } satisfies Config;

Then include the @tailwind directives in your CSS. For example, you could create a tailwind.css file at the root of your app:

  1. @tailwind base;
  2. @tailwind components;
  3. @tailwind utilities;

Then add tailwind.css to your root route’s links function:

  1. import type { LinksFunction } from "@remix-run/node"; // or cloudflare/deno
  3. // ...
  5. import styles from "./tailwind.css";
  7. export const links: LinksFunction = () => [
  8.   { rel: "stylesheet", href: styles },
  9. ];

With this setup in place, you can also use Tailwind’s functions and directives anywhere in your CSS. Note that Tailwind will warn that no utility classes were detected in your source files if you never used it before.

If you’re also using Remix’s built-in PostCSS support, the Tailwind PostCSS plugin will be automatically included if it’s missing, but you can also choose to manually include the Tailwind plugin in your PostCSS config instead if you prefer.

If you’re using VS Code, it’s recommended you install the Tailwind IntelliSense extension for the best developer experience.

It’s recommended that you avoid Tailwind’s @import syntax (e.g. @import 'tailwindcss/base') in favor of Tailwind directives (e.g. @tailwind base). Tailwind replaces its import statements with inlined CSS but this can result in the interleaving of styles and import statements. This clashes with the restriction that all import statements must be at the start of the file. Alternatively, you can use PostCSS with the postcss-import plugin to process imports before passing them to esbuild.

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-run/node"; // or cloudflare/deno
  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

PostCSS is a popular tool with a rich plugin ecosystem, commonly used to prefix CSS for older browsers, transpile future CSS syntax, inline images, lint your styles and more. When a PostCSS config is detected, Remix will automatically run PostCSS across all CSS in your project.

For example, to use Autoprefixer, first enable the postcss option in remix.config.js:

  1. /** @type {import('@remix-run/dev').AppConfig} */
  2. module.exports = {
  3.   postcss: true,
  4.   // ...
  5. };

Install the PostCSS plugin.

  1. npm install -D autoprefixer

Then add postcss.config.js in the Remix root referencing the plugin.

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

If you’re using Vanilla Extract, since it’s already playing the role of CSS preprocessor, you may want to apply a different set of PostCSS plugins relative to other styles. To support this, you can export a function from postcss.config.js which is given a context object that lets you know when Remix is processing a Vanilla Extract file.

  1. module.exports = (ctx) => {
  2.   return ctx.remix?.vanillaExtract
  3.     ? {
  4.         // PostCSS plugins for Vanilla Extract styles...
  5.       }
  6.     : {
  7.         // PostCSS plugins for other styles...
  8.       };
  9. };

CSS Preprocessors

You can use CSS preprocessors like LESS and SASS. Doing so requires running an additional build process to convert these files to CSS files. This can be done via the command line tools provided by the preprocessor or any equivalent tool.

Once converted to CSS by the preprocessor, the generated CSS files can be imported into your components via the Route Module links export function, or included via side-effect imports when using CSS bundling, just like any other CSS file in Remix.

To ease development with CSS preprocessors you can add npm scripts to your package.json that generate CSS files from your SASS or LESS files. These scripts can be run in parallel alongside any other npm scripts that you run for developing a Remix application.

An example using SASS.

  1. First you’ll need to install the tool your preprocess uses to generate CSS files.
  1. npm add -D sass
  1. Add an npm script to your package.json‘s script section’ that uses the installed tool to generate CSS files.
  1. {
  2.   // ...
  3.   "scripts": {
  4.     // ...
  5.     "sass": "sass --watch app/:app/"
  6.   }
  7.   // ...
  8. }

The above example assumes SASS files will be stored somewhere in the app folder.

The --watch flag included above will keep sass running as an active process, listening for changes to or for any new SASS files. When changes are made to the source file, sass will regenerate the CSS file automatically. Generated CSS files will be stored in the same location as their source files.

  1. Run the npm script.
  1. npm run sass

This will start the sass process. Any new SASS files, or changes to existing SASS files, will be detected by the running process.

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

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

Running npm run dev will run the specified commands in parallel in a single terminal window.

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 affect performance in a significant way; React is pretty fast.

Here’s some sample code to show how you might use Styled Components with Remix (you can also find a runnable example in the Remix examples repository):

  1. First you’ll need to put a placeholder in your root component to control where the styles are inserted.

    1. import type { MetaFunction } from "@remix-run/node"; // or cloudflare/deno
    2. import {
    3.   Links,
    4.   LiveReload,
    5.   Meta,
    6.   Outlet,
    7.   Scripts,
    8.   ScrollRestoration,
    9. } from "@remix-run/react";
    11. export const meta: MetaFunction = () => ({
    12.   charset: "utf-8",
    13.   viewport: "width=device-width, initial-scale=1",
    14. });
    16. export default function App() {
    17.   return (
    18.     <html lang="en">
    19.       <head>
    20.         <Meta />
    21.         <Links />
    22.         {typeof document === "undefined"
    23.           ? "__STYLES__"
    24.           : null}
    25.       </head>
    26.       <body>
    27.         <Outlet />
    28.         <ScrollRestoration />
    29.         <Scripts />
    30.         <LiveReload />
    31.       </body>
    32.     </html>
    33.   );
    34. }

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

    1. import type {
    2.   AppLoadContext,
    3.   EntryContext,
    4. } from "@remix-run/node"; // or cloudflare/deno
    5. import { RemixServer } from "@remix-run/react";
    6. import { renderToString } from "react-dom/server";
    7. import { ServerStyleSheet } from "styled-components";
    9. export default function handleRequest(
    10.   request: Request,
    11.   responseStatusCode: number,
    12.   responseHeaders: Headers,
    13.   remixContext: EntryContext,
    14.   loadContext: AppLoadContext
    15. ) {
    16.   const sheet = new ServerStyleSheet();
    18.   let markup = renderToString(
    19.     sheet.collectStyles(
    20.       <RemixServer
    21.         context={remixContext}
    22.         url={request.url}
    23.       />
    24.     )
    25.   );
    26.   const styles = sheet.getStyleTags();
    27.   markup = markup.replace("__STYLES__", styles);
    29.   responseHeaders.set("Content-Type", "text/html");
    31.   return new Response("<!DOCTYPE html>" + markup, {
    32.     status: responseStatusCode,
    33.     headers: responseHeaders,
    34.   });
    35. }

Other CSS-in-JS libraries will have a similar setup. If you’ve got a CSS framework working well with Remix, please contribute an example!

NOTE: You may run into hydration warnings when using Styled Components. Hopefully this issue will be fixed soon.

CSS Bundling

When using CSS-bundling features, you should avoid using export * due to an issue with esbuild’s CSS tree shaking.

Many common approaches to CSS within the React community are only possible when bundling CSS, meaning that the CSS files you write during development are collected into a separate bundle as part of the build process.

When using CSS-bundling features, the Remix compiler will generate a single CSS file containing all bundled styles in your application. Note that any regular stylesheet imports will remain as separate files.

Unlike many other tools in the React ecosystem, we do not insert the CSS bundle into the page automatically. Instead, we ensure that you always have control over the link tags on your page. This lets you decide where the CSS file is loaded relative to other stylesheets in your app.

To get access to the CSS bundle, first install the @remix-run/css-bundle package.

  1. npm install @remix-run/css-bundle

Then, import cssBundleHref and add it to a link descriptor—most likely in root.tsx so that it applies to your entire application.

  1. import { cssBundleHref } from "@remix-run/css-bundle";
  2. import type { LinksFunction } from "@remix-run/node"; // or cloudflare/deno
  4. export const links: LinksFunction = () => {
  5.   return [
  6.     ...(cssBundleHref
  7.       ? [{ rel: "stylesheet", href: cssBundleHref }]
  8.       : []),
  9.     // ...
  10.   ];
  11. };

With this link tag inserted into the page, you’re now ready to start using the various CSS bundling features built into Remix.

CSS Modules

To use the built-in CSS Modules support, first ensure you’ve set up CSS bundling in your application.

You can then opt into CSS Modules via the .module.css file name convention. For example:

  1. .root {
  2.   border: solid 1px;
  3.   background: white;
  4.   color: #454545;
  5. }
  1. import styles from "./styles.module.css";
  3. export const Button = React.forwardRef(
  4.   ({ children, ...props }, ref) => {
  5.     return (
  6.       <button
  7.         {...props}
  8.         ref={ref}
  9.         className={styles.root}
  10.       />
  11.     );
  12.   }
  13. );
  14. Button.displayName = "Button";

Vanilla Extract

Vanilla Extract is a zero-runtime CSS-in-TypeScript (or JavaScript) library that lets you use TypeScript as your CSS preprocessor. Styles are written in separate *.css.ts (or *.css.js) files and all code within them is executed during the build process rather than in your user’s browser. If you want to keep your CSS bundle size to a minimum, Vanilla Extract also provides an official library called Sprinkles that lets you define a custom set of utility classes and a type-safe function for accessing them at runtime.

To use the built-in Vanilla Extract support, first ensure you’ve set up CSS bundling in your application.

Then, install Vanilla Extract’s core styling package as a dev dependency.

  1. npm install -D @vanilla-extract/css

You can then opt into Vanilla Extract via the .css.ts/.css.js file name convention. For example:

  1. import { style } from "@vanilla-extract/css";
  3. export const root = style({
  4.   border: "solid 1px",
  5.   background: "white",
  6.   color: "#454545",
  7. });
  1. import * as styles from "./styles.css"; // Note that `.ts` is omitted here
  3. export const Button = React.forwardRef(
  4.   ({ children, ...props }, ref) => {
  5.     return (
  6.       <button
  7.         {...props}
  8.         ref={ref}
  9.         className={styles.root}
  10.       />
  11.     );
  12.   }
  13. );
  14. Button.displayName = "Button";

CSS Side-Effect Imports

Some NPM packages use side-effect imports of plain CSS files (e.g. import "./styles.css") to declare the CSS dependencies of JavaScript files. If you want to consume one of these packages, first ensure you’ve set up CSS bundling in your application.

Since JavaScript runtimes don’t support importing CSS in this way, you’ll need to add any relevant packages to the serverDependenciesToBundle option in your remix.config.js file. This ensures that any CSS imports are compiled out of your code before running it on the server. For example, to use React Spectrum:

  1. /** @type {import('@remix-run/dev').AppConfig} */
  2. module.exports = {
  3.   serverDependenciesToBundle: [
  4.     /^@adobe\/react-spectrum/,
  5.     /^@react-spectrum/,
  6.     /^@spectrum-icons/,
  7.   ],
  8.   // ...
  9. };