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.
The createStyled function in @stitches/react has been renamed to createCss.
- import { createStyled } from '@stitches/react';
+ import { createCss } from '@stitches/react';
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();
The tokens key in the configuration has been renamed to theme.
createCss({
- tokens: {}
+ theme: {}
});
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'
})
A couple of things here:
The breakpoints key in the configuration has been renamed to media.
A media is now a key-value pair. No more function.
The value should omit the at-rule @media itself.
createCss({
- breakpoints: {
+ media: {
- bp1: (rule) => `@media (min-width: 640px) { ${rule} }`,
+ bp1: '(min-width: 640px)'
}
});
Support for proxy has been removed.
- styled.button({})
+ styled('button', {})
To use tokens you need to prefix them with a dollar sign ($).
const Button = styled('button', {
- color: 'red'
+ color: '$red'
});
To chain pseudo-classes or pseudo-elements you need to use the nesting selector (&).
const Button = styled('button', {
- '&:hover': {}
+ '&:hover': {}
- '::before': {}
+ '&::before': {}
});
You need to prefix media queries with an @ sign.
const Button = styled('button', {
- bp1: {}
+ '@bp1': {}
})
You need to prefix the initial key with an @ sign.
You need to prefix media queries with an @ sign.
const Button = styled('button', {
- initial: {}
+ '@initial': {}
- bp1: {}
+ '@bp1': {}
})
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',
- },
- })
A couple of things here:
The getStyle function has been renamed to getCssString.
The getCssString function takes no arguments. Call it to render your styles.
- const { result, styles } = css.getStyles(() => renderSomething());
+ const styles = getCssString()
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.
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'
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'
}
}
})
You can now define the class to be generated when creating additional themes.
+ const darkTheme = theme('dark-theme', {})
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',
+ }
})
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'
}
})
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'
})
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'
@import ruleYou 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']
})
@font-face ruleYou 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")'
+ }]
})
@supports ruleYou can now use @supports rules.
const globalStyles = global({
+ '@supports (display: grid)': {
+ body: {
+ display: grid
+ }
+ }
})
const Grid = styled('div', {
+ '@supports (display: grid)': {
+ display: grid
+ }
})
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
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' })} />
)
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.
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'
+}
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.