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: a styleObject
const Button = styled('button', {
// base styles
variants: {
variant: {
primary: {
// primary styles
},
secondary: {
// secondary styles
},
},
},
});

A function to generate class names from a style object. It receives a styleObject.

const card = css({
backgroundColor: 'gray',
border: '1px solid black',
borderRadius: '6px',
});
() => <div className={card()}>Card content</div>;

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

const globalStyles = global({
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: getCssString() }} />

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

import { defaultThemeMap } from '@stitches/react';
createCss({
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 { createCss } from '@stitches/react';
createCss({
theme: object,
media: object,
utils: object,
prefix: string,
insertionMethod: string | function,
themeMap: object,
});

The createCss function returns the following:

  • styled: a function to create React components with styles.
  • css: a function to create CSS rules.
  • global: a function to create global styles.
  • keyframes: a function to create keyframes.
  • theme: a function for creating additional themes.
  • getCssString: a function get styles as a string, useful for SSR.
  • config: an object contianing the hydrated config.
const { styled, css, global, keyframes, theme, getCssString, config } = createCss();

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

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

Set up reusable breakpoints.

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

The media config supports range queries by default:

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

Set up custom utils to improve your developer experience.

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

Prefix all classnames to avoid clashes.

createCss({
prefix: 'radix-',
});

Define how the style tag is inserted. Available values are:

  • prepend (default) - style tag will be inserted as the first child of the head element.
  • append - style tag will be inserted as the last child of the head element. This is useful if you're including third party CSS and want Stitches to have a higher specificity.
  • function - custom function, you're in control.
createCss({
insertionMethod() {
let currentCssHead: null;
let currentCssNode: null;
return (cssText) => {
if (typeof document === 'object') {
if (!currentCssHead) currentCssHead = document.head || document.documentElement;
if (!currentCssNode)
currentCssNode =
document.getElementById('stitches') ||
Object.assign(document.createElement('style'), { id: 'stitches' });
if (!currentCssNode.parentNode) currentCssHead.append(currentCssNode);
currentCssNode.textContent = cssText;
}
};
},
});

Define custom mapping of CSS properties to theme tokens.

createCss({
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.

A function to override the default theme passed into the createCss function. This function is only available from createCss.

It receives a theme object.

const { theme } = createCss({
theme: {
colors: {
background: 'white',
foreground: 'black',
},
},
});
export const darkTheme = theme({
colors: {
background: 'black',
foreground: 'white',
},
});
({ children }) => <div className={darkTheme}>{children}</div>;

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

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

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
// dark theme
+ dark.colors.foreground.value; // white + dark.colors.foreground.token; // foreground + dark.colors.foreground.scale; // colors + dark.colors.foreground.variable; // --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.