@stitches/core

What is @stitches/core?

@stitches/core is a CSS-in-JS library that provides a performant, flexible, and feature-rich way to style your applications. It allows you to write CSS with JavaScript, offering features like theming, responsive design, and utility-first styling.

What are @stitches/core's main functionalities?

Styling Components

This feature allows you to create styled components using the `styled` function. You can define styles directly in your JavaScript code and apply them to HTML elements.

const { styled } = require('@stitches/core');

const Button = styled('button', {
  backgroundColor: 'blue',
  color: 'white',
  padding: '10px 20px',
  borderRadius: '5px',
  '&:hover': {
    backgroundColor: 'darkblue'
  }
});

Theming

Theming allows you to define different themes for your application. You can create multiple themes and switch between them dynamically.

const { createTheme } = require('@stitches/core');

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

const lightTheme = createTheme({
  colors: {
    background: 'white',
    text: 'black'
  }
});

Responsive Design

This feature allows you to define responsive styles using media queries. You can specify different styles for different screen sizes.

const { styled } = require('@stitches/core');

const Container = styled('div', {
  width: '100%',
  '@media (min-width: 768px)': {
    width: '50%'
  }
});

Utility-First Styling

Utility-first styling allows you to create utility classes that can be reused across your application. This promotes consistency and reduces the amount of CSS you need to write.

const { css } = require('@stitches/core');

const utilityClass = css({
  margin: '10px',
  padding: '20px',
  backgroundColor: 'lightgray'
});

Other packages similar to @stitches/core

styled-components

styled-components is another popular CSS-in-JS library that allows you to write actual CSS to style your components. It offers similar features like theming and dynamic styling but uses tagged template literals for defining styles.

emotion

Emotion is a performant and flexible CSS-in-JS library. It provides both a styled API and a css API, giving you the flexibility to choose how you want to style your components. It also supports theming and server-side rendering.

linaria

Linaria is a zero-runtime CSS-in-JS library. It allows you to write CSS in your JavaScript files but extracts the CSS at build time, resulting in no runtime overhead. It supports theming and dynamic styling.

README

Why

• Atomic mindset: Each CSS property is an atomic part of your complete CSS
• Reusability: Each CSS property, given the same screen, pseudo and value is considered the same, giving high degree of reusability
• Optimal injection: You can compose your styles outside of your UI, but no injection happens until it is actually used
• Tokenized: Configure with tokens to give design restrictions
• Screens: Define a set of media queries as screens to easily express CSS active within a screen
• Utils: Create your own CSS properties
• Typed: Fully typed API, even though you are not using Typescript
• Specificity solved: No more specificity issues, as an atomic mindset opens up a more efficient and straight forward way to solve it
• Token based theming: Tokens are CSS variables. Create themes overriding the tokens and expose themes to any parts of your app

A simple benchmark VS styled-components

Get started

npm install @stitches/core

import { css } from '@stitches/core';

const button = css({
  color: 'gray',
  '&:hover': {
    color: 'black',
  },
  borderColor: 'black',
  padding: '1rem',
});

const alertButton = css(button, {
  borderColor: 'red',
});

const dynamicButton = (disabled = false) =>
  css(
    button,
    disabled && {
      opacity: 0.5,
    }
  );

Configure an instance

import { createCss } from '@stitches/core';

export const css = createCss({
  // Optinally add a prefix to all classnames to avoid crashes
  prefix: 'my-lib',
  // Maps tokens to properties. Follows the system-ui theme specification: https://system-ui.com/theme
  tokens: {
    colors: {
      RED: 'tomato',
    },
    space: {
      0: '1rem',
    },
    fontSizes: {},
    fonts: {},
    fontWeights: {},
    lineHeights: {},
    letterSpacings: {},
    sizes: {},
    borderWidths: {},
    borderStyles: {},
    radii: {},
    shadows: {},
    zIndices: {},
    transitions: {},
  },
  // Create screens with media queries. Note that the media queriy with the
  // highest specificity should go last
  breakpoints: {
    tablet: (rule) => `@media (min-width: 700px) { ${rule} }`,
  },
  // Create your own custom CSS properties. Here the functional syntax
  // shines to handle pseudo selectors
  utils: {
    marginX: (config) => (value: number | string) => ({
      marginLeft: value,
      marginRight: value,
    }),
  },
});

css({
  color: 'RED', // Creates "tomato"
  tablet: {
    color: 'blue', // Color is "blue" when media query is active
  },
  marginX: 0, // Creates "1rem", as it composes margin, using "space" from tokens
  border: '1px solid RED', // creates a "tomato" border
  border: ['1px', 'solid', 'RED'], // You can also use array syntax to get typing
  boxShadow: ['1px', '1px', '1px', 'RED'], // You can also use array syntax with shadow
});

Utility first

Stitches also allows you to put your utils at the front. That means you can create your very own CSS abstraction, where the underlying CSS properties are secondary.

import { createCss } from '@stitches/core';

export const css = createCss({
  utilityFirst: true,
  utils: {
    text: (config) => (value: { color?: string; size?: number }) => ({
      ...(color ? { color } : {}),
      ...(size ? { fontSize: size + 'rem' } : {}),
    }),
  },
});

css({
  text: {
    color: 'red',
    size: 2,
  },
  ':hover': {
    text: {
      color: 'blue',
    },
  },
  // Override is a property that allows you to override
  // with specific low level CSS properties
  override: {
    padding: '2rem',
  },
});

Themes

You can create theme instances which overrides tokens:

import { createCss } from '@stitches/core';

export const css = createCss({
  tokens: {
    colors: {
      primary: 'tomato',
    },
  },
});

export const funnyTheme = css.theme({
  colors: {
    primary: 'pink',
  },
});

This theme represents a classname which can be added at any point in your DOM tree. You can add multiple themes, which overrides each other by the nested level you apply them.

Server side rendering

The createCss factory automatically detects if you are in a browser or server environment. That means when you this factory on the server it will hash the classnames (for rehydration abilities) and allow you to collect the styling to include in the responded html:

import { createCss } from '@stitches/core';

const css = createCss({});
const { result, styles } = css.getStyles(() => renderSomething(css));

Note that server produced CSS does not contain vendor prefixes, as there is no browser environment to look at. If you have a server rendered application you can either manually add the vendor prefixes you need:

css({
  WebkitFontSmoothing: 'antialiased',
  MozOsxFontSmoothing: 'grayscale',
});

Or you can use a postcss to do the conversion:

import { createCss } from '@stitches/core';
import postcss from 'postcss';
import autoprefixer from 'autoprefixer';

const css = createCss({});
const { result, styles } = css.getStyles(() => renderSomething(css));

Promise.all(
  styles.map((style) => postcss([autoprefixer({ browsers: ['> 1%', 'last 2 versions'] })]).process(style))
).then((styles) => {
  // styles with vendor prefixes
});