API

The nuts and bolts of Stitches' API.

A function to create a component including its styles and variants. It receives:

  • element or component: a HTML element (div) or a React Component (Component)

  • styles: as many styleObject as you need

const Button = styled('button', {
// base styles
variants: {
variant: {
primary: {
// primary styles
},
secondary: {
// secondary styles
},
},
},
});
// Use it
<Button>Button</Button>
<Button variant="primary">Primary button</Button>

A function to generate class names from a style object. It receives as many styleObject as you need.

const button = css({
// base styles
variants: {
variant: {
primary: {
// primary styles
},
secondary: {
// secondary styles
},
},
},
});
// Use it
<div className={button()}>Button</div>
<div className={button({ variant: 'primary' })}>Primary button</div>

For handling things like global resets, you can write global CSS styles.

const globalStyles = globalCss({
body: { margin: 0 },
});
() => {
globalStyles();
return <div />;
};

A function to create a global CSS @keyframe rule.

const scaleUp = keyframes({
'0%': { transform: 'scale(1)' },
'100%': { transform: 'scale(1.5)' },
});
const Button = styled('button', {
'&:hover': {
animation: `${scaleUp} 200ms`,
},
});

A function to generate styles on the server-side.

<style id="stitches" dangerouslySetInnerHTML={{ __html: getCssText() }} />

You can import defaultThemeMap if you want to merge with the default mapping.

import { createStitches, defaultThemeMap } from '@stitches/react';
createStitches({
themeMap: {
...defaultThemeMap,
width: 'space',
height: 'space',
},
});

This function is used to configure Stitches. You can use this function if you need to add default theme tokens, custom utilities, media queries, etc.

import { createStitches } from '@stitches/react';
createStitches({
theme: object,
media: object,
utils: object,
prefix: string,
themeMap: object,
});

The createStitches function returns the following:

  • styled: a function to create React components with styles.

  • css: a function to create CSS rules.

  • globalCss: a function to create global styles.

  • keyframes: a function to create keyframes.

  • theme: a function for accessing default theme data.

  • createTheme: a function for creating additional themes.

  • getCssText: a function get styles as a string, useful for SSR.

  • config: an object containing the hydrated config.

const {
styled,
css,
globalCss,
keyframes,
theme,
createTheme,
getCssText,
config,
} = createStitches();

Set up your design theme tokens. You can then use them in the style object.

createStitches({
theme: {
colors: {},
space: {},
fontSizes: {},
fonts: {},
fontWeights: {},
lineHeights: {},
letterSpacings: {},
sizes: {},
borderWidths: {},
borderStyles: {},
radii: {},
shadows: {},
zIndices: {},
transitions: {},
},
});

Set up reusable breakpoints.

createStitches({
media: {
bp1: '(min-width: 640px)',
bp2: '(min-width: 768px)',
bp3: '(min-width: 1024px)',
},
});

The media config supports range queries by default:

createStitches({
media: {
toBp2: '(width <= 768px)',
},
});

Set up custom utils to improve your developer experience.

createStitches({
utils: {
// A property for applying width/height together
size: (value) => ({
width: value,
height: value,
}),
// A property to apply linear gradient
linearGradient: (value) => ({
backgroundImage: `linear-gradient(${value})`,
}),
// An abbreviated property for background-color
bg: (value) => ({
backgroundColor: value,
}),
},
});

Prefix all class names and CSS variables to avoid global clashes.

createStitches({
prefix: 'radix',
});

Define custom mapping of CSS properties to theme tokens.

createStitches({
themeMap: {
// Map these properties to the `space` scale
width: 'space',
height: 'space',
},
});

Here's a list of the default mapping.

Note: this overrides the default mapping. Import defaultThemeMap to merge with default.

An object containing default theme data.

const { theme } = createStitches({
theme: {
colors: {
background: 'white',
foreground: 'black',
},
},
});

You can use the returned theme object to apply the default theme class, this is specially useful when using multiple themes:

<div className={theme}>Content here</div>

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

// default theme
+ theme.colors.foreground.value; // black + theme.colors.foreground.token; // foreground + theme.colors.foreground.scale; // colors + theme.colors.foreground.variable; // --colors-foreground + theme.colors.foreground.computedValue; // var(--colors-foreground)

A function to override the default theme passed into the createStitches function. It receives a theme object.

export const darkTheme = createTheme({
colors: {
background: 'black',
foreground: 'white',
},
});

You can define the theme class to used by passing it as the first argument:

export const darkTheme = createTheme('dark-theme', {...});

You can use the returned theme object to apply the default theme class:

<div className={darkTheme}>{children}</div>

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

// dark theme
+ dark.colors.foreground.value; // white + dark.colors.foreground.token; // foreground + dark.colors.foreground.scale; // colors + dark.colors.foreground.variable; // --colors-foreground + dark.colors.foreground.computedValue; // var(--colors-foreground)

CSS but written as a JavaScript object.

{
color: 'red',
backgroundColor: 'red',
fontSize: '13px',
'&:hover': {
color: 'black'
},
'&.chained': {
color: 'black'
},
'& .descendant': {
color: 'black'
},
'@media (min-width: 400px)': {
fontSize: '16px'
}
}

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

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

You can pick a token from any of your available theme scales by prefixing them with the scale name.

const Button = styled('button', {
// apply a color token to a locally scoped token
$$shadowColor: '$colors$purple500',
boxShadow: '0 0 0 15px $$shadowColor'
// use a token from the sizes scale
marginTop: '$sizes$1'
})

All components created via the styled function support a polymorphic as prop. This prop is useful for changing the rendering element of a component. You can also use the as prop to render another component.

const Button = styled('button', {
// base styles
});
() => (
<Button as="a" href="https://github.com/modulz/stitches">
GitHub
</Button>
);

If you're using TypeScript the attributes will change based on the element type provided.