Theme Configuration

Customizing the default theme for your project.

xstyled includes a defaultTheme, recommended to start a project, it includes colors, type scale, fonts, breakpoints, border radii, and more.

Theme structure

Theme object contains keys for screens, colors, space and every utilities available.

See the theme configuration reference or the default theme for a complete list of theme options.

Screens

The screens key allows you to customize the responsive breakpoints in your project.

export const theme = {
  screens: {
    _: 0,
    sm: '640px',
    md: '768px',
    lg: '1024px',
    xl: '1280px',
    '2xl': '1536px',
  },
}

Colors

The colors key allows you to customize the global color palette for your project.

export const theme = {
  colors: {
    black: '#000',
    white: '#fff',
    'gray-100': '#f7fafc',
    // ...
    'gray-900': '#1a202c',
    // ...
  },
}

These values are used for every utilities: backgroundColor, borderColor, textColor, and others...

To learn more, see the color customization documentation.

Spacing

The space key allows you to customize the global spacing and sizing scale for your project.

export const theme = {
  space: {
    px: '1px',
    0: '0',
    0.5: '0.125rem',
    1: '0.25rem',
    1.5: '0.375rem',
    2: '0.5rem',
    2.5: '0.625rem',
    3: '0.75rem',
    3.5: '0.875rem',
    4: '1rem',
    5: '1.25rem',
    6: '1.5rem',
    7: '1.75rem',
    8: '2rem',
    9: '2.25rem',
    10: '2.5rem',
    11: '2.75rem',
    12: '3rem',
    14: '3.5rem',
    16: '4rem',
    20: '5rem',
    24: '6rem',
    28: '7rem',
    32: '8rem',
    36: '9rem',
    40: '10rem',
    44: '11rem',
    48: '12rem',
    52: '13rem',
    56: '14rem',
    60: '15rem',
    64: '16rem',
    72: '18rem',
    80: '20rem',
    96: '24rem',
  },
}

These values are used for every space relative utilities: padding, margin, gap, and others...

Core Plugins

Each utility has its own section. For example radii key lets you customize which border radius utilities will be generated:

export const theme = {
  radii: {
    none: '0',
    sm: '.125rem',
    default: '.25rem',
    lg: '.5rem',
    full: '9999px',
  },
}

The keys are automatically transformed when you use borderRadius utility.

<x.div borderRadius="sm" />
// will generate CSS: "border-radius: .125em;"

The key default is used when you specify "default" or true. Since true is the default in JSX, it lets you shorten the property.

<x.div borderRadius />
// will generate CSS: "border-radius: .25em;"

For a complete reference of available theme properties and their default values, see the default theme configuration.

Customizing the default theme

To start an xstyled project, it is heavily recommended to use the defaultTheme. It is very easy to extends thanks to object spread operator.

For example, if you wanted to add an extra breakpoint but preserve the existing ones, you could extend the screens property:

import { defaultTheme, ThemeProvider } from '@xstyled/styled-components'

export const theme = {
  ...defaultTheme,
  // Adds a new breakpoint in addition to the default breakpoints
  screens: {
    ...defaultTheme.screens,
    '3xl': '1600px',
  },
}

Overriding the default theme

To override defaultTheme, do not spread default theme properties.

import { defaultTheme, ThemeProvider } from '@xstyled/styled-components'

export const theme = {
  ...defaultTheme,
  // Only two breakpoints will be available
  screens: {
    md: '800px',
    xl: '1200px',
  },
}

Referencing other values

You can refer other values using th.* utility.

import { th, defaultTheme, ThemeProvider } from '@xstyled/styled-components'

export const theme = {
  ...defaultTheme,
  colors: {
    ...defaultTheme,
    // Use `red-500` as `primary` color
    primary: th.color('red-500'),
  },
}

It works recursively, so you can use several level of design tokens:

import { th, defaultTheme, ThemeProvider } from '@xstyled/styled-components'

export const theme = {
  ...defaultTheme,
  colors: {
    ...defaultTheme,
    primary: th.color('red-500'),
    'button-bg': th.color('primary'),
  },
}

Adding you own keys

Some keys are used by xstyled, but it does not mean you can't specify others.

For example if you create a custom filter utility, or if you use it by your own, you can add a filters section:

import { defaultTheme, ThemeProvider } from '@xstyled/styled-components'

export const theme = {
  ...defaultTheme,
  filters: {
    grayscale: 'grayscale(1)',
    invert: 'invert(1)',
    sepia: 'sepia(1)',
  },
}

Configuration reference