Getting Started

Follow these few steps to get ready with xstyled.

Introduction

xstyled is composed of two packages @xstyled/system and @xstyled/styled-components:

  • @xstyled/system exposes all core utilities, it is similar to styled-system and it works with styled-components and emotion.
  • @xstyled/styled-components is a wrapper around styled-components to enable the system directly in the CSS syntax.

If you wonder why we need both or why we don't use styled-system, read Motivation first.

Installation

To download xstyled run:

npm install @xstyled/styled-components styled-components

That's all you need to do, you are now ready to use it in your app! (yep, no build step needed 👌)

xstyled is just a wrapper around styled-components, it means that it is recommended (but not required) to also use the styled-components Babel plugin if you can. It offers many benefits like more legible class names, server-side rendering compatibility, smaller bundles, and more.

If you want to use emotion instead, see Use with emotion

Style your first component

If you are familiar with styled-components, xstyled is the same thing with super powers!

Instead of importing styled-components, use @xstyled/styled-components.

import styled from '@xstyled/styled-components'
const Button = styled.button``

You can style this button with CSS of course, but also with system based CSS. Let's try it:

const Button = styled.button`
background: transparent;
border-radius: 3px;
border: 2px solid;
border-color: violet;
color: violet;
margin: 0 16px;
padding: 4px 16px;
`

The above button is only CSS. It is great, but it would be nice to replace everything with theme based value, let's try it.

const Button = styled.button`
background: transparent;
border-radius: 3px;
border: 2px solid;
border-color: ${(props) => props.theme.colors.primary};
color: ${(props) => props.theme.colors.primary};
margin: 0 ${(props) => props.theme.space[3]};
padding: ${(props) => props.theme.space[1]} ${(props) => props.theme.space[3]};
`

That's ugly isn't it? xstyled syntax simplifies it! It brings the power of @xstyled/system right in CSS syntax:

const Button = styled.button`
background: transparent;
border-radius: 3;
border: 2;
border-color: primary;
color: primary;
margin: 0 3;
padding: 1 3;
`

You can now use all your theme based values in your CSS!

If it looks too magic for you? Start with theme getters.