Stitches homepage
Blog

Migration guide: Stitches alpha to beta

A guide to help you migrate from Stitches alpha to beta.

Pedro Duarte

12 min readChangelog

You can use this guide to help with the migration from Stitches alpha to beta (v0.1.0).

The API is mostly the same, with a few small breaking changes, listed below.

Renamed import

The createStyled function in @stitches/react has been renamed to createCss.

- import { createStyled } from '@stitches/react'; + import { createCss } from '@stitches/react';

Independent functions

The css object no longer attaches functions such as global, keyframes and theme.

You need to destructure them from createCss.

const { css } = createCss();
- css.theme() - css.global() - css.keyframes() - css.getStyles()
const {
css, styled, + global, + theme, + keyframes, + getCssString } = createCss();

Theme configuration

The tokens key in the configuration has been renamed to theme.

createCss({
- tokens: {} + theme: {} });

Token prefixing

You no longer need to prefix your tokens with a dollar sign ($).

createCss({
theme: { - $gray500: 'hsl(206,10%,76%)', + gray500: 'hsl(206,10%,76%)', } });

But you must use the $ to reference them:

styled('button', {
color: '$gray500'
})

Breakpoints configuration

A couple of things here:

createCss({
- breakpoints: { + media: { - bp1: (rule) => `@media (min-width: 640px) { ${rule} }`, + bp1: '(min-width: 640px)' } });

No more proxy

Support for proxy has been removed.

- styled.button({}) + styled('button', {})

Using tokens

To use tokens you need to prefix them with a dollar sign ($).

const Button = styled('button', {
- color: 'red' + color: '$red' });

Chaining pseudo classes and elements

To chain pseudo-classes or pseudo-elements you need to use the nesting selector (&).

const Button = styled('button', {
- '&:hover': {} + '&:hover': {} - '::before': {} + '&::before': {} });

Responsive styles

You need to prefix media queries with an @ sign.

const Button = styled('button', {
- bp1: {} + '@bp1': {} })

Responsive variants

const Button = styled('button', {
- initial: {} + '@initial': {} - bp1: {} + '@bp1': {} })

Compound variants

You can now specify compound variants with a special compoundVariants array in the style object.

const Button = styled('button', {
variants: { color: { violet: {}, gray: {}, }, appearance: { outline: {} } }, + compoundVariants: [{ + color: 'violet', + appearance: 'outline', + css: { + color: 'blueviolet', + borderColor: 'darkviolet', + '&:hover': { + color: 'white', + }, + } + }] })
- Button.compoundVariant({ - color: 'violet', - appearance: 'outline', - }, { - color: 'blueviolet', - borderColor: 'darkviolet', - '&:hover': { - color: 'white', - }, - })

Server-side rendering

A couple of things here:

- const { result, styles } = css.getStyles(() => renderSomething()); + const styles = getCssString()

Applying classnames

When using the css function, you now call the Stitches component to apply the class.

const button = css({})
() => (
- <Button className={button} /> + <Button className={button()} /> )

We've also introduced some exciting new features, here's an overview.

Quick import

You can now import the css, styled, global, keyframes, and getCssString functions directly. This is useful if you dont need any configuration.

+ import { css } from '@stitches/core' + import { css, styled, global, keyframes, getCssString } from '@stitches/react'

Token aliases

You can now create semantic tokens by referencing tokens on the same scale. As always, use the $ to reference a token.

createCss({
theme: { colors: { gray500: 'hsl(206,10%,76%)', + primary: '$gray500' } } })

Choose your theme class

You can now define the class to be generated when creating additional themes.

+ const darkTheme = theme('dark-theme', {})

Default variants

You can now set default variants in css and styled functions with a defaultVariants key in the style object.

const Button = styled('button', {
variants: { color: { violet: {}, gray: {}, }, appearance: { outline: {} } }, + defaultVariants: { + color: 'violet', + } })

Customisable property mapping

You can now map your own properties to scales with the themeMap configuration.

createCss({
themeMap: { + height: 'space', + width: 'space' } })

If you wish to merge with the default mapping, you can import and spread defaultThemeMap. This is available from @stitches/core and @stitches/react.

import { defaultThemeMap } from '@stitches/core'
createCss({
themeMap: { + ...defaultThemeMap, + height: 'space', + width: 'space' } })

Scale-prefixed tokens

You can now access tokens from a speecific scale by prefixing it with the scale name. For example, by default margin maps to the space scale, but you can access a token from the sizes scale using the scale-prefix.

const Button = styled('button', {
+ margin: '$sizes$4' })

Locally scoped tokens

You can now create a token directly within a style object by prefixing it with two dollar signs ($$).

const Button = styled('button', {
+ $$shadowColor: 'blueviolet', + boxShadow: '0 0 0 15px $$shadowColor' })

Any token can reference another token from any specific scale:

+ $$shadowColor: '$colors$purple400'

Support for @import rule

You can now use @import rules within the global function.

const globalStyles = global({
+ '@import': 'custom.css' })

Or if you need multiple values, use an array:

const globalStyles = global({
+ '@import': ['custom1.css', 'custom2.css'] })

Support for @font-face rule

You can now use @font-face rules within the global function.

const globalStyles = global({
+ '@font-face': { + fontFamily: 'CustomFont', + src: 'local("CustomFont"), url("CustomFont.woff2")' + } })

Or if you need multiple values, use an array:

const globalStyles = global({
+ '@font-face': [{ + fontFamily: 'CustomFont1', + src: 'local("CustomFont1"), url("CustomFont1.woff2")' + }, { + fontFamily: 'CustomFont2', + src: 'local("CustomFont2"), url("CustomFont2.woff2")' + }] })

Support for @supports rule

You can now use @supports rules.

const globalStyles = global({
+ '@supports (display: grid)': { + body: { + display: grid + } + } })
const Grid = styled('div', {
+ '@supports (display: grid)': { + display: grid + } })

Theme object

The theme is now an object containing useful token data.

For example, given the following default theme and dark themes:

const { theme } = createCss({
theme: {
colors: {
primary: 'black',
},
},
});
const dark = theme({
colors: {
primary: 'white',
},
});

You can use the returned theme objects to read the tokens, like so:

// default theme
+ theme.colors.primary.value; // black + theme.colors.primary.token; // primary + theme.colors.primary.scale; // colors + theme.colors.primary.variable; // --colors-primary
// dark theme
+ dark.colors.primary.value; // white + dark.colors.primary.token; // primary + dark.colors.primary.scale; // colors + dark.colors.primary.variable; // --colors-primary

Core variant support

The @stitches/core package now supports variants, as well as defaultVariants and compoundVariants.

const button = css('button', {
+ variants: { + color: { + violet: {}, + gray: {}, + }, + } })
() => (
+ <Button className={button({ color: 'violet' })} /> )

Core override support

The @stitches/core package now supports overrides with the css prop.

const button = css('button', {})
() => (
+ <Button className={button({ css: { display: 'none' } })} /> )

We've introduced some type helpers which can be useful when using Stitches components.

Abstract styles

You can abstract style objects while still get typing with by creating with the help of the StitchesCss generic.

This is available in both @stitches/core and @stitches/react.

// stitches.config.ts
+ import createCss, { StitchesCss } from '@stitches/core';
+ const stitchesConfig = createCss({ theme: { colors: { gray500: 'hsl(206,10%,76%)', } } });
+ const { css } = stitchesConfig
+ export type CSS = StitchesCss<typeof stitchesConfig>;
+ const sharedStyles: CSS = { + backgroundColor: '$gray500' +}

Extract variants

You can extract the variants of a component with the StitchesVariants type.

This is available in both @stitches/core and @stitches/react.

+ import { StitchesVariants } from '@stitches/core';
+ type ButtonVariants = StitchesVariants<typeof button>;
const button = css('button', {
variants: { color: { violet: {}, gray: {}, }, } })

Share this post on Twitter.