@vanilla-extract/recipes

What is @vanilla-extract/recipes?

@vanilla-extract/recipes is a package that provides a way to define and manage design tokens and styles in a type-safe manner. It allows you to create reusable style recipes that can be easily shared and maintained across your application.

What are @vanilla-extract/recipes's main functionalities?

Creating a Recipe

This feature allows you to create a recipe for a button component with different variants for color and size. The `recipe` function helps in defining base styles and variants, making it easy to manage and reuse styles.

const buttonRecipe = recipe({
  base: {
    padding: '10px 20px',
    borderRadius: '5px',
    border: 'none',
    cursor: 'pointer'
  },
  variants: {
    color: {
      primary: { backgroundColor: 'blue', color: 'white' },
      secondary: { backgroundColor: 'gray', color: 'black' }
    },
    size: {
      small: { fontSize: '12px' },
      large: { fontSize: '18px' }
    }
  },
  defaultVariants: {
    color: 'primary',
    size: 'small'
  }
});

Using a Recipe

This feature demonstrates how to use a recipe in a React component. The `buttonRecipe` function is called with the desired variants to apply the appropriate styles to the button.

import { buttonRecipe } from './styles.css';

const Button = ({ color, size, children }) => {
  return (
    <button className={buttonRecipe({ color, size })}>
      {children}
    </button>
  );
};

Other packages similar to @vanilla-extract/recipes

styled-components

styled-components is a popular library for styling React components using tagged template literals. It allows you to write actual CSS to style your components. Compared to @vanilla-extract/recipes, styled-components offers a more traditional approach to styling with CSS-in-JS, but lacks the type safety and design token management features.

emotion

Emotion is another library for writing CSS styles with JavaScript. It provides both a styled API similar to styled-components and a css function for writing styles. Emotion offers a good balance between performance and flexibility, but like styled-components, it does not provide the same level of type safety and design token management as @vanilla-extract/recipes.

twin.macro

twin.macro is a library that allows you to use Tailwind CSS classes within styled-components or Emotion. It combines the utility-first approach of Tailwind CSS with the power of CSS-in-JS libraries. While it offers a different approach to styling, it does not provide the type-safe design token management that @vanilla-extract/recipes offers.

README

🧁 vanilla-extract

Zero-runtime Stylesheets-in-TypeScript.

Write your styles in TypeScript (or JavaScript) with locally scoped class names and CSS Variables, then generate static CSS files at build time.

Basically, it’s “CSS Modules-in-TypeScript” but with scoped CSS Variables + heaps more.

🔥   All styles generated at build time — just like Sass, Less, etc.

✨   Minimal abstraction over standard CSS.

🦄   Works with any front-end framework — or even without one.

🌳   Locally scoped class names — just like CSS Modules.

🚀   Locally scoped CSS Variables, @keyframes and @font-face rules.

🎨   High-level theme system with support for simultaneous themes. No globals!

🛠   Utils for generating variable-based calc expressions.

💪   Type-safe styles via CSSType.

🏃‍♂️   Optional runtime version for development and testing.

🙈   Optional API for dynamic runtime theming.

---

🌐 Check out the documentation site for setup guides, examples and API docs.

---

🖥   Try it out for yourself in CodeSandbox.

---

Write your styles in .css.ts files.

// styles.css.ts

import { createTheme, style } from '@vanilla-extract/css';

export const [themeClass, vars] = createTheme({
  color: {
    brand: 'blue'
  },
  font: {
    body: 'arial'
  }
});

export const exampleStyle = style({
  backgroundColor: vars.color.brand,
  fontFamily: vars.font.body,
  color: 'white',
  padding: 10
});

💡 Once you've configured your build tooling, these .css.ts files will be evaluated at build time. None of the code in these files will be included in your final bundle. Think of it as using TypeScript as your preprocessor instead of Sass, Less, etc.

Then consume them in your markup.

// app.ts

import { themeClass, exampleStyle } from './styles.css.ts';

document.write(`
  <section class="${themeClass}">
    <h1 class="${exampleStyle}">Hello world!</h1>
  </section>
`);

---

Want to work at a higher level while maximising style re-use? Check out 🍨 Sprinkles, our official zero-runtime atomic CSS framework, built on top of vanilla-extract.

---

Thanks

• Nathan Nam Tran for creating css-in-js-loader, which served as the initial starting point for treat, the precursor to this library.
• Stitches for getting us excited about CSS-Variables-in-JS.
• SEEK for giving us the space to do interesting work.

License

MIT.