Migrate from styled-components

Differences with styled-components and migration guide to xstyled.

Differences with styled-components

Declarative components

xstyled is a kind of styled-components with super powers. It adds lot of utilities accessible on a special x.* component or directly using original styled.* syntax.

The philosophy of xstyled is to use x.* as much as possible.

Using styled-components

import styled from 'styled-components' const Button = styled.button` padding: 0.5rem 1rem; color: white; border-radius: 0.375rem; font-weight: 600; transition: background-color cubic-bezier(0.4, 0, 0.2, 1) 150ms; background-color: #10b981; &:hover { background-color: #065f46; } &:focus { outline: none; box-shadow: 0 0 0 3px #10b98180; } `

Using xstyled

import { x } from '@xstyled/styled-components' const Button = props => ( <x.button py={2} px={4} color="white" borderRadius="md" fontWeight="semibold" transition bg="emerald-500" hoverBg="emerald-800" focusOutline="none" focusRing focusRingColor="emerald-500-a50" {...props} /> )

As you can see xstyled is fully declarative and much more productive than using styled-components.

Read declarative components guide to learn more about this approach.

Enhanced styled components

We know you could not be convinced by x.* approach. That's why xstyled could help you to be more productive with styled.* approach too.

Most projects follow a design system, a set of space, colors, fonts.. that define the constraints and the universe of a project.

To follow a design system with styled-components, the common way is to use the theme.

Using styled-components

import styled from 'styled-components' const Button = styled.button` padding: ${p => `${p.theme.space[2]} ${p.theme.space[4]}`}; color: ${p => p.theme.colors.white}; border-radius: ${p => p.theme.radii.md}; font-weight: ${p => p.theme.fontWeights.semibold}; transition: ${p => p.theme.transitions.default}; background-color: ${p => p.theme.colors['emerald-500']}; &:hover { background-color: ${p => p.theme.colors['emerald-800']}; } &:focus { outline: none; box-shadow: ${p => p.theme.shadows['emerald-ring']}; } `

Using xstyled

import styled from '@xstyled/styled-components' const Button = styled.button` padding-top: 2; padding-bottom: 2; padding-right: 4; padding-left: 4; color: white; border-radius: md; font-weight: semibold; transition: default; background-color: emerald-500; &:hover { background-color: emerald-800; } &:focus { outline: none; box-shadow: emerald-ring; } `

Read enhanced styled components guide to learn more about this approach.

Responsive utilities

xstyled has great responsive utilities to simplify usage of media queries.

Using styled-components

import styled from 'styled-components' const Button = styled.div` width: 200px; @media (min-width: 768px) { width: 300px; } `

Using xstyled's x.*

import { x } from '@xstyled/emotion' const Button = ({ children }) => { return <x.button w={{ _: 200, md: 300 }}>{children}</x.button> }

Using xstyled's styled.*

import styled, { up, css } from '@xstyled/styled-components' const Button = styled.div` width: 200; ${up( 'md', css` width: 300; `, )} `

Replacing styled-components by xstyled

@xstyled/styled-components is a drop-in replacement for styled-components. You can safely replace styled-components by @xstyled/styled-components.

Once your code is using xstyled, you can start using declarative components (x.*) and enhanced styled components (styled.*).

css prop is not supported

Styled Components css prop is not supported by xstyled. We don't plan to support it since xstyled philosophy is to use x.* instead.

Styled Components css prop rely on a Babel transformation to work. Some edge-cases like using state in a CSS property are not supported. We recommended to not use it. If your codebase uses it, then you should migrate to xstyled's x.*.

❌ The following code does not work even with just styled-components

function Example() { const [value, setValue] = useState(false) return ( <div css={` color: ${value ? 'red' : 'blue'}; `} /> ) }

Babel plugin

You may want to use styled-components Babel plugin to add support for server-side rendering, minification of styles, and a nicer debugging experience.

You can use it out of the box, but you have to specify xstyled as topLevelImportPaths:

// .babelrc { "plugins": [ [ "babel-plugin-styled-components", { "topLevelImportPaths": [ "@xstyled/styled-components", "@xstyled/styled-components/no-tags", "@xstyled/styled-components/native", "@xstyled/styled-components/primitives" ], } ] ] }

Babel Macro

Unfortunately Babel Macro is not yet supported by xstyled.

Edit this page on GitHub