TypeScript

Out of the box TypeScript experience.

Stitches provides typing out of the box, but this page contains some further utilities and tips.

You can import all the types at once:

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

These include:

• Stitches.CSS

• Stitches.VariantProps

• Stitches.PropertyValue

• Stitches.ScaleValue

The recommended way to share styles across components is to create them via the css or the styled functions. This way you'll get typing for free.

import { css, styled } from '@stitches/react';

const sharedColor = css({ color: 'red' });
const sharedTypography = css({ fontFamily: 'system-ui' });
const Text = styled('span', sharedColor, sharedTypography);
const Heading = styled('h1', Text);

But you can use Stitches.CSS to type it manually.

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

const sharedColor: Stitches.CSS = { color: 'red' };
const sharedTypography: Stitches.CSS = { fontFamily: 'system-ui' };
const Text = styled('span', sharedColor, sharedTypography);
const Heading = styled('h1', Text);

If you've configured Stitches, make sure to pass your config to the Stitches.CSS generic.

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

const { css, styled, config } = createStitches({ ...yourConfig });
type CSS = Stitches.CSS<typeof config>;

const sharedColor: CSS = { color: 'red' };
const sharedTypography: CSS = { fontFamily: 'system-ui' };
const Text = styled('span', sharedColor, sharedTypography);
const Heading = styled('h1', Text);

The Stitches.CSS utility is also useful for when creating custom components that accept a css prop:

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

const Button = styled('button', {});

// Use `Stitches.CSS` or the configured type as shown above
type MyButtonProps = { css?: Stitches.CSS };
const MyButton = function (props: MyButtonProps) {
  return <Button {...props} />;
};

You can use the Stitches.VariantProps utility to extract variants from a component. This ensures your variants support responsive syntax.

import { css, styled } from '@stitches/react';
import type * as Stitches from '@stitches/react';

const cssButton = css({
  variants: {
    size: {
      1: {},
      2: {},
    }
  }
})

const StyledButton = styled('button', {
  variants: {
    size: {
      1: {},
      2: {},
    }
  }
})

type CSSButtonVariants = Stitches.VariantProps<typeof cssButton>
type StyledButtonVariants = Stitches.VariantProps<typeof StyledButton>

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'
})

Here are some tips if you want a more strict experience.

Use the theme object to access your tokens, this way, you can rely on TypeScript to rename them. This will also give you an error if a token is removed.

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

const { css, styled, theme } = createStitches({
  theme: {
    colors: {
      purple500: 'hsl(252,78%,60%)',
    }
  }
})

const cssButton = css({
  color: theme.colors.purple500
})

const StyledButton = styled('button', {
  color: theme.colors.purple500
})