Introduction
The what and the why of Stitches.
Stitches is a lightweight, performant styling library with a focus on component architecture and developer experience.
At Modulz, performance is paramount. 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 ~6kb gzipped.
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.
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.
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.
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 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,
}),
},
});
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)',
},
});
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>
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.
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!
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.