Styled System

Style props for rapid UI development

npm i styled-system
Getting StartedResponsive StylesCustom PropsVariantsHow it WorksAPIReference TablePackagesEcosystemTheme SpecificationArticlesGuidesGitHub
ghstarsBuild StatusDownloadsVersionsizeMIT Licensespectrum-badgesystem-ui/theme

Expressive, consistent UI components

Styled System lets you quickly build custom UI components with constraint-based style props based on scales defined in your theme.

import styled from '@emotion/styled'
import { typography, space, color } from 'styled-system'

const Box = styled('div')(
  mb={[ 4, 5 ]}
  • Primitive building blocks for component-based design systems
  • Style props that pick up values from a global theme
  • Quickly set responsive font-size, margin, padding, width, and more
  • Inspired by constraint-based design system principles
  • Typographic scale for consistent design
  • White space scale for margin, padding, and layout
  • Supports any color palette
  • Works with most CSS-in-JS libraries, including Styled Components and Emotion
  • This is honestly my favourite way to build UI components right now
    Varun Vachhar
  • If you haven’t seen Styled System before, do yourself a favour and check it out. It’s been a huge influence in my thinking on component-oriented styles.
    Mark Dalgleish
  • The future of css-in-js is going to look something like styled-system with its responsive values.
    Kye Hohenberger
  • Coming from @tachyons_css, the styled-system utilities from @jxnblk is the missing link I’ve been looking for.
    Nathan Young
  • If you make websites/apps with React check out Styled System if you haven’t already. You will be amazed at how much faster you can build.
    David Yeiser
  • If you like Tachyons you will love styled-system. If you don’t like Tachyons, you will love styled-system.
    Adam Morse
  • Styled System is one of the best libraries I have ever used.
    Miha Sedej

Used by

  • GitHub logo
  • Artsy logo
  • Cloudflare logo
  • Priceline logo
  • Guides

Getting Started

Styled System is a collection of utility functions that add style props to your React components and allows you to control styles based on a global theme object with typographic scales, colors, and layout properties.

To use Styled System, install a CSS-in-JS library such as Styled Components or Emotion.

npm i styled-system styled-components

Create a Component

Create a new component that uses style functions from Styled System. To start with, add the color function to the component's styles argument.

import styled from 'styled-components'
import { color } from 'styled-system'

const Box = styled.div`

export default Box

Now, this component will have two style props available: color to set foreground color, and bg to set background color. (You can also use backgroundColor if you're adverse to terse naming conventions.)

<Box color="#fff" bg="tomato">

So far, this component can be styled with any valid CSS color. To create a more consistent UI, create a theme module with a colors object.

// theme.js
export default {
  colors: {
    black: '#000e1a',
    white: '#fff',
    blue: '#007ce0',
    navy: '#004175',


Most CSS-in-JS libraries include a ThemeProvider to provide values through React context. Import the styled-components ThemeProvider in the root of your application and pass the theme to the theme prop.

import React from 'react'
import { ThemeProvider } from 'styled-components'
import theme from './theme'

const App = props => (
  <ThemeProvider theme={theme}>{/* application elements */}</ThemeProvider>

export default App

With the ThemeProvider added, the Box component now has access to the colors defined in the theme object.

<Box color="black" bg="blue">
  Blue Box

Styled System will attempt to find a value based on keys in the theme and fallback to the raw value if it's not defined in the theme.

// this example uses the CSS color keyword `tomato` since it's not defined in the theme
<Box bg="tomato" />

To make the Box component a little more useful, add a few more Styled System functions to handle layout styles.

import styled from 'styled-components'
import { space, layout, color } from 'styled-system'

const Box = styled.div`

export default Box

If you prefer using the plain object syntax, you can pass Styled System functions in as arguments.

// example using object syntax
const Box = styled('div')(
    boxSizing: 'border-box',

Margin & Padding

The space function adds margin and padding props. The margin and padding props use a shorthand syntax, similar to Basscss, Tachyons, and Bootstrap.

Margin Props

  • m margin
  • mt margin-top
  • mr margin-right
  • mb margin-bottom
  • ml margin-left
  • mx margin-left and margin-right
  • my margin-top and margin-bottom

Padding Props

  • p padding
  • pt padding-top
  • pr padding-right
  • pb padding-bottom
  • pl padding-left
  • px padding-left and padding-right
  • py padding-top and padding-bottom

Note: you can also use longform prop names (e.g. margin, paddingTop) if you prefer.

Space Theming

To set a consistent negative-space scale, add a space array to your theme. Use numbers to set pixel values, or use strings for other CSS units such as rem. It's recommended to set 0 as the first value in the array.

// theme.js
export default {
  space: [0, 4, 8, 16, 32, 64, 128, 256, 512],

All spacing props accept numbers, strings, or arrays as values, where:

  • Numbers between 0 and the last index of the space array are values from the space array defined in theme
  • Numbers greater than the length of the space array are converted to pixels
  • String values can be used for any valid CSS value (e.g. 'auto' or '2em')
  • Margin props accept negative values to set negative margin
  • Arrays can be used for responsive styles
  • Note: numeric strings without a CSS unit will be used as indices for the array (e.g. space['0'])


The layout function adds props for widths, heights, display, and more. Widths and heights can use values defined in theme.sizes to help ensure consistency in layout styles.

The width prop accepts number, string, or array values, where:

  • Numbers between 0 and 1 are converted to percentage based widths (e.g. 1/2 becomes '50%')
  • Numbers greater than 1 are converted to pixels
  • Strings can be used for other CSS values (e.g. '50vw' or '30em')
  • Arrays can be used for responsive styles
  • If an array is used to define theme.sizes, width={0} will return theme.sizes[0] and width={1} will return theme.sizes[1]

Responsive Styles

All Styled System functions accept arrays as values to set styles responsively using a mobile-first approach.

    1, // 100% below the smallest breakpoint (all viewports)
    1 / 2, // 50% from the next breakpoint and up
    1 / 4, // 25% from the next breakpoint and up
// responsive margin
<Text m={[ 0, 1, 2 ]} />

// responsive padding
<Text p={[ 2, 3, 4 ]} />

// responsive font-size
<Text fontSize={[ 3, 4, 5 ]} />

Read the Responsive Styles docs for more information.

Other Props

Styled System includes pre-built functions for many other commonly used CSS properties. For a complete list, see the Reference Table of style functions.

Edit this page on GitHub