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 to 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.

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 be 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/stitchesjs/stitches">
    GitHub
  </Button>
);