Migration guide: Stitches beta to v1

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

You can use this guide to help with the migration from Stitches beta to v1.

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

- const { css, theme, ... } = createCss()
+ const { css, theme, ... } = createStitches()

- const globalStyles = global()
+ const globalStyles = globalCss()

- getCssString()
+ getCssText()

The theme object can still be used to access your token data and reset your theme class. But it's no longer a theme creator function. Use createTheme to create a new theme.

- const darkTheme = theme()
+ const darkTheme = createTheme()

createStitches({
  utils: {
-   bc: (config) => (value) => { backgroundColor: value }
+   bc: (value) => { backgroundColor: value }
  }
})

import { createStitches } from '@stitches/react';
import type * as Stitches from '@stitches/react';

const { config } = createStitches()
- type CSS = Stitches.StitchesCss<typeof config>
+ type CSS = Stitches.CSS<typeof config>

import { createStitches } from '@stitches/react';
import type * as Stitches from '@stitches/react';

const Box = styled('div', {
  variants: {
    size: {
      small: {}
    }
  }
})
- type BoxVariants = Stitches.StitchesVariants<typeof Box>
+ type BoxVariants = Stitches.VariantProps<typeof Box>

Stitches v1 introduces a few new features and APIs, check these out below.

Use the Stitches.PropertyValue utility when the value can be:

• a valid value of a given CSS property.

• a valid token of its mapped theme map.

This utility receives one argument, and it's a CSS property.

import type * as Stitches from '@stitches/react';

const { styled } = createStitches({
  theme: {
    colors: {
      primary: 'blueviolet',
      secondary: 'gainsboro',
    }
  },
  utils: {
    bc: (value: Stitches.PropertyValue<'backgroundColor'>) => ({
      backgroundColor: value
    })
  }
});

const Box = styled('div', {
  // TypeScript will suggest valid values and tokens
  // values such as `red`, `inherit`, `transparent`, etc
  // tokens such as `$primary` and `$secondary`
  bc: '$primary'
})

Use the Stitches.ScaleValue utility when the value can be:

• a valid token of its mapped theme map.

This utility receives one argument, and it's a scale name.

import type * as Stitches from '@stitches/react';

const { styled } = createStitches({
  theme: {
    space: {
      1: '5px',
      2: '10px',
    }
  },
  utils: {
    mt: (value: Stitches.ScaleValue<'space'>) => ({
      marginTop: value
    })
  }
});

const Box = styled('div', {
  // TypeScript will suggest valid tokens
  // tokens such as `$1` and `$2`
  mt: '$1'
})