Blog

Introducing Stitches

The modern CSS-in-JS library with near-zero runtime.

Stitches is a lightweight, performant styling library with a focus on component architecture and developer experience.

In this post I'll provide an overview of our goals and priorities, and highlight some features.

Near-Zero Runtime

At Modulz, performance is paramount. We use WebGL where possible, but in the React layer, we need things as fast as possible too. So when designing Stitches, performance was a top priority.

Stitches avoids unnecessary prop interpolations at runtime, making it significantly more performant than other styling libraries.

Both @stitches/core and @stitches/react libraries weigh in at ~6.0kb gzipped.

Server-Side Rendering

Many UI libraries document that responsive variants don't work with server-side rendering. Since popular frameworks like Next.js and Gatsby have begun prioritising SSR, we wanted a solution that works well.

Stitches supports cross-browser server-side rendering, even for responsive styles and variants.

Variants

Stitches introduces variants as a first-class citizen, so you can design composable component APIs.

You can define a single variant, multiple variants, and even compound variants which allow you to define styles based on a combination of variants.

Variants can be applied conditionally or responsively.

Tokens

One of the most exciting features is the ability to define your own tokens and seamlessly apply them as CSS values. CSS Properties are automatically mapped to token scales. Tokens can even be used in shorthand CSS properties.

Theming

Stitches provides a simple theming experience out of the box. Create as many themes as you need, and apply them wherever you want. Each theme generates a CSS class name which overrides the default tokens.

const darkTheme = createTheme({
  colors: {
    hiContrast: 'hsl(206,2%,93%)',
    loContrast: 'hsl(206,8%,8%)',

    gray100: 'hsl(206,8%,12%)',
    gray200: 'hsl(206,7%,14%)',
    gray300: 'hsl(206,7%,15%)',
    gray400: 'hsl(206,7%,24%)',
    gray500: 'hsl(206,7%,30%)',
    gray600: 'hsl(206,5%,53%)',
  },
  space: {},
  fonts: {},
});

Utils

Utils allow you to create your own custom CSS Properties, with your own API.

Use utils to create powerful combinations of properties, property aliases and to introduce restrictions when needed.

export const { styled, css } = createStitches({
  utils: {
    marginX: (value) => ({
      marginLeft: value,
      marginRight: value,
    }),
    marginY: (value) => ({
      marginTop: value,
      marginBottom: value,
    }),
  },
});

Responsive Variants

Stitches lets you configure breakpoints and apply variants responsively using the css prop. CSS at-rules can also be used inline if needed.

export const { styled, css } = createStitches({
  media: {
    bp1: '(min-width: 640px)',
    bp2: '(min-width: 768px)',
    bp3: '(min-width: 1024px)',
    bp4: '(min-width: 1280px)',
  },
});

Overrides

Stitches provides a css prop for overriding styles on any Stitches component. You can use this prop to define layout concerns and/or overrides. Tokens and breakpoints also work in the css prop.

<Button css={{ backgroundColor: 'red' }}>Button</Button>

Stitches also provides a polymorphic as prop for defining which tag a component renders.

<Text as="h1">Heading</Text>
<Text as="p">Paragraph</Text>

Developer Experience

One of our main goals is to provide the best possible developer experience. Stitches provides a fully-typed API, so when using TypeScript, CSS properties, values, and breakpoints will be auto-completed for you.

Also, when using the as prop, the prop suggestions will update.

1. Install it

npm install @stitches/react

2. Set it up

import { createStyled } from '@stitches/react';

export const { styled, css } = createStitches({
  tokens: {
    colors: {
      gray100: 'hsl(206,22%,99%)',
      gray200: 'hsl(206,12%,97%)',
      gray300: 'hsl(206,11%,92%)',
      gray400: 'hsl(206,10%,84%)',
      gray500: 'hsl(206,10%,76%)',
    },
    space: {
      1: '5px',
      2: '10px',
      3: '15px',
    },
    fontSizes: {
      1: '12px',
      2: '13px',
      3: '15px',
    },
  },
});

3. Style your first component

const Button = styled('button', {
  backgroundColor: '$gray300',
  borderRadius: '9999px',
  fontSize: '$2',
  lineHeight: '1',
  fontWeight: 500,
  padding: '$2 $3',
  border: '0',

  '&:hover': {
    backgroundColor: '$gray500',
  },
});

render(<Button>Button</Button>);

You can learn more about how to use Stitches in our documentation.

We're excited to see the community adopt Stitches, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!

• Discord

• Twitter

• GitHub Discussions

• GitHub

We're grateful for everyone who contributed and provided feedback along the way.

Special thanks to Jonathan Neal for the commitment and dedication to building a best-in-class library, being true to current and future CSS specs.

Special thanks to Pedro Duarte for the API design, thorough testing, roadmap and documentation.

Special thanks to Abdulhadi Alhallak for the relentless wars with TypeScript to provide the best possible developer experience.

Special thanks to Colm Tuite and Stephen Haney for bringing Stitches under the Modulz organisation and dedicating a team to maintaining it.