Upgrade Guide

Upgrading from xstyled v1.x to v2.0.

xstyled v2 is the new major version since v1 of xstyled released in May 2019.

We know that xstyled is in the core of your project and that the migration could be difficult. For that purpose, we minimized the number of changes between the two versions, there is only few breaking changes.

New philosophy

The v2 of xstyled favoured the usage of the x instead of the styled approach. Even if the styled approach is always supported, it is better to use x as much as possible!

import { x } from '@xstyled/...'

function Button() {
  return (
    <x.button
      type="button"
      color="white"
      transition
      bg="emerald-500"
      hoverBg="emerald-800"
    >
      Upgrade
    </x.button>
  )
}

Remember class Components and Hooks in React? It is the same thing for x and styled. There is no plan of deprecation, no need to convert all your code but it is better to use x if you can in future.

Breaking changes

Emotion v11

xstyled v2 works with Emotion v11, if you use xstyled v1 with Emotion, please read the migrate guide from Emotion v10 to Emotion v11 first.

No more default space

xstyled v1 had default space built-in, in v2 space are now located in default theme and are slightly different from v1. Two options:

• If you have customized space in your theme:

Good news! You don't have to do anything, just keep your them in v2.

• If you have not customized space in your theme:

Use old space in your theme:

const theme = {
  space: [0, 4, 8, 16, 24, 48, 96, 144, 192, 240],
}

• If you were not using any theme:

Read customize theme documentation to learn how to create a theme.

gridGap becomes gap

To follow the new specification, gridGap becomes gap.

• If you use gridGap in your project:

Replace it by gap.

width becomes w, height becomes h

To reduce conflict between image attributes width and height, only w and h are now usable to define CSS properties width and height.

• If you use width or height in your project:

Replace it by w and h.

No more size utility

To reduce conflict between input attribute size, size .

• If you use size in your project:

Replace it by w + h.

No more forwardedAs

Everything is now simplified, you don't have to worry about forwardedAs any more, as works everywhere.

• If you use forwardedAs:

• Replace it by as.

Utilities groups reorganization

xstyled v2 exposes lot of new utilities, to be more consistent, utilities groups have been completely changed.

• If you use utility groups like backgrounds, basics, borders, flexboxes, grids, layout, positioning, shadows, space, svg, typography or xgrids:

You have to pick new groups of utilities or single utilities. Read how to create utilities to learn more about it.

Breakpoints

xstyled v2 now uses the same breakpoints as Tailwind, it was using Bootstrap's one but landscape have changed and those from Tailwind are actually more realistic. Also, breakpoints are now read from screens theme key.

• If you use breakpoints and does not define them:

Add xstyled v1 breakpoints:

const theme = {
  screens: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
}

• If you already use your own breakpoints:

Migrate them to screens:

  const theme = {
-   breakpoints: { xs: 0, md: 800 },
+   screens: { xs: 0, md: 800 },
  }

No more variant utility

variant utility was confusing and not really helpful, xstyled v2 encourages to use the x.* syntax, so it is no longer required.

• If you want use variant utility and you want to get it back:

Add variant utility in your codebase:

import { getThemeValue, merge, warn, is, assign } from '@xstyled/util'

const variant = ({
  key = null,
  default: defaultValue,
  variants = {},
  prop = 'variant',
}) => (props) => {
  const themeVariants = is(key) ? getThemeValue(props, key) : null
  const computedVariants = merge(assign({}, variants), themeVariants)
  const value = props[prop] !== undefined ? props[prop] : defaultValue
  const result = getThemeValue(props, value, computedVariants)
  warn(is(result), `variant "${value}" not found`)
  return result
}