styled-system

What is styled-system?

Styled System is a utility for creating consistent, responsive, and theme-based design systems in React. It provides a set of functions and utilities to style components using a system of design tokens, such as spacing, colors, and typography, making it easier to build UI components that adhere to a design system.

What are styled-system's main functionalities?

Responsive Styles

Styled System allows you to define responsive styles using arrays. The `p` prop sets padding, `bg` sets background color, and `width` sets the width of the component. The values in the arrays correspond to different breakpoints.

const Box = styled.div`
  ${space}
  ${color}
  ${layout}
`;

<Box p={[1, 2, 3]} bg={['red', 'green', 'blue']} width={[1, 1/2, 1/4]} />

Theme-based Design

Styled System integrates with a theme object to provide consistent styling across your application. The `color` and `space` utilities use the theme to apply styles.

const theme = {
  colors: {
    primary: 'blue',
    secondary: 'green',
  },
  space: [0, 4, 8, 16, 32],
};

const Box = styled.div`
  ${color}
  ${space}
`;

<Box color='primary' p={2} />

Utility Functions

Styled System provides utility functions like `space`, `color`, and `layout` that can be used to style components. These functions map props to CSS properties based on the theme.

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

const Box = styled.div`
  ${space}
  ${color}
  ${layout}
`;

<Box m={2} p={3} bg='primary' width={1/2} />

Other packages similar to styled-system

emotion

Emotion is a library designed for writing CSS styles with JavaScript. It provides powerful and flexible styling capabilities, including support for theming and responsive styles. Compared to Styled System, Emotion offers more granular control over CSS but requires more manual setup for design systems.

styled-components

Styled-components is a library for styling React components using tagged template literals. It allows for writing actual CSS to style components and supports theming and dynamic styling. While it doesn't provide the same utility functions as Styled System, it can be used in conjunction with Styled System for a more comprehensive solution.

tailwindcss

Tailwind CSS is a utility-first CSS framework that provides low-level utility classes for building custom designs. It offers a different approach compared to Styled System by using predefined classes instead of JavaScript functions. Tailwind CSS is highly customizable and can be used to create responsive and theme-based designs.

README

styled-system

Design system utilities for styled-components, glamorous, and other css-in-js libraries

npm i styled-system

Usage

// With styled-components
import styled from 'styled-components'
import { space, width, fontSize, color } from 'styled-system'

const Box = styled.div`
  ${space}
  ${width}
  ${fontSize}
  ${color}
`

// Or with glamorous
import glamorous from 'glamorous'
import { space, width, fontSize, color } from 'styled-system'

const Box = glamorous.div(space, width, fontSize, color)

// width: 50%
<Box width={1/2} />

// font-size: 20px
<Box fontSize={4} />

// margin: 16px
<Box m={2} />

// padding: 32px
<Box p={3} />

// color
<Box color='tomato' />
<Box color='grays.0' />

// background color
<Box bg='tomato' />

// responsive width
<Box width={[ 1, 1/2, 1/4 ]} />

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

// responsive margin
<Box m={[ 1, 2, 3 ]} />

// responsive padding
<Box p={[ 1, 2, 3 ]} />

width

import { width } from 'styled-system'

The width utility parses a component's width prop and converts it into a CSS width declaration.

Numbers from 0-1 are converted to percentage widths. Numbers greater than 1 are converted to pixel values. String values are passed as raw CSS values. And arrays are converted to responsive width styles.

fontSize

import { fontSize } from 'styled-system'

The fontSize utility parses a component's fontSize prop and converts it into a CSS font-size declaration. Numbers from 0-8 are converted to values on the font size scale. Numbers greater than 8 are converted to raw pixel values. String values are passed as raw CSS values. And array values are converted into responsive values.

space

import { space } from 'styled-system'

The space utility converts shorthand margin and padding props to margin and padding CSS declarations. Numbers from 0-4 are converted to values on the spacing scale. Negative values can be used for negative margins. Numbers greater than 4 are converted to raw pixel values. String values are converted passed as raw CSS values. And array values are converted into responsive values.

Margin and padding props follow a shorthand syntax for specifying direction.

• 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
• 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

color

import { color } from 'styled-system'

The color utility parses a component's color and bg props and converts them into CSS declarations. By default the raw value of the prop is returned. Color palettes can be configured with the ThemeProvider to use keys as prop values, with support for dot notation. Array values are converted into responsive values.

Responsive Styles

All props accept arrays as values for mobile-first responsive styles.

// 100% below the smallest breakpoint,
// 50% from the next breakpoint and up,
// and 25% from the next breakpoint and up
<Box w={[ 1, 1/2, 1/4 ]} />

// responsive font size
<Box fontSize={[ 1, 2, 3, 4 ]} />

// responsive margin
<Box m={[ 1, 2, 3, 4 ]} />

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

responsiveStyle

The responsiveStyle utility can be used to handle array-based responsive style props for other CSS properties.

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

// Usage
// responsiveStyle(cssProperty[, propName][, booleanValue])

const Flex = styled.div`
  display: flex;
  ${responsiveStyle('flex-direction', 'direction')}
`

const App = props => (
  <Flex direction={[ 'column', 'row' ]}>
    <div>Responsive</div>
    <div>Direction</div>
  </Flex>
)

Remove Props

Styled-components attempts to remove invalid HTML attributes from props, but does not remove width, fontSize, or color. When using styled-system with other CSS-in-JS libraries, it can also be helpful to remove style props. To ensure style props are not passed to the element, a removeProps utility can be used.

import React from 'react'
import styled from 'styled-components'
import {
  width,
  fontSize,
  space,
  removeProps
} from 'styled-system'

const BaseComponent = props => {
  const next = removeProps(props)
  return <div {...next} />
}

const Component = styled(BaseComponent)([],
  width,
  fontSize,
  space
)

Breakpoints

styled-system uses a mobile-first responsive approach, where any value set works from that breakpoint and wider. The default set of breakpoints aims to cover a wide range of devices from mobile to desktop. Breakpoints default to em but can be overridden by passing strings with unit appended. Breakpoints can be customized using styled-components' ThemeProvider.

[ 40, 52, 64 ]
// @media screen and (min-width: 40em)
// @media screen and (min-width: 52em)
// @media screen and (min-width: 64em)

[ '300px', '600px', '1200px' ]
// @media screen and (min-width: 300px)
// @media screen and (min-width: 600px)
// @media screen and (min-width: 1200px)

Font Size Scale

Using a typographic scale helps create visual rhythm and reduces the number of decisions needed when designing UI. Styled system uses a modular scale that covers most of a UI's needs, but it can be customized with styled-components' ThemeProvider.

[ 12, 14, 16, 20, 24, 32, 48, 64, 72 ]

Spacing Scale

Using a scale for spacing helps ensure elements line up, even when nested inside one another. styled-system uses a spacing scale based on an 8px, powers-of-two grid for margin and padding by default and can be customized with styled-components' ThemeProvider.

[ 0, 8, 16, 32, 64 ]

Configuration

styled-system can be configured with styled-components' ThemeProvider

As opposed to the built-in configurations, arrays given to the breakpoints, space, and fontSizes theme properties can be of arbitrary lengths.

import { ThemeProvider } from 'styled-components'
// or import { ThemeProvider } from 'glamorous'
import MyComponent from './MyComponent'

const theme = {
  breakpoints: [
    32, 48, 64
  ],
  space: [
    0, 6, 12, 18, 24
  ],
  fontSizes: [
    12, 16, 18, 24, 36, 72
  ],
  colors: {
    black: '#111',
    blue: '#07c',
  }
}

const App = props => (
  <ThemeProvider theme={theme}>
    <MyComponent
      fontSize={4}
      my={[ 2, 3 ]}
      color='blue'
    />
  </ThemeProvider>
)

Related

• grid-styled
• Rebass
• styled-components
• glamorous

MIT License