xstyled Documentation

xstyled is designed to be highly performant and includes a comprehensive set of utilities for building design systems.

Bundle Size

The package size is approximately ~15kb gzipped, which includes all utilities and dependencies. This is intended to provide a complete toolkit for a website or design system out of the box.

• @xstyled/styled-components: ~15.4kb gzipped
• @xstyled/emotion: ~15.7kb gzipped

Runtime Performance

• Computation: Every property computation is cached to minimize overhead.
• Rendering: xstyled has no measurable impact on the rendering phase compared to standard styled-components.
• Evaluation: There is a small impact during the evaluation phase because xstyled uses RegExp to detect properties in CSS. However, this impact is considered negligible compared to React's hydration or mounting phases.

If you do not provide a durations section in your theme, xstyled uses a default set of durations based on Google Material Design recommendations.

const defaultTheme = {
  // ...
  durations: {
    instant: '100ms',
    'fast-in': '250ms',
    'fast-out': '200ms',
    'slow-in': '300ms',
    'slow-out': '250ms',
  },
}

You can conditionally apply transitions based on user accessibility preferences using motionSafe and motionReduce states within the transition object.

For example, you can enable transitions by default but disable them if the user has requested reduced motion via motionReduce: 'none'.

<x.button
  color={{ hover: 'red' }}
  transition={{ _: true, motionReduce: 'none' }}
>
  Hover me
</x.button>

Benchmarks comparing @xstyled/system to styled-system show that while styled-system may have a higher operations-per-second count, xstyled provides additional features that account for the difference:

• Responsive Styles Ordering: xstyled ensures correct ordering for responsive styles.
• Nested Theme Caching: xstyled supports nested theme caching, which styled-system does not.
• API Flexibility: xstyled offers a more flexible API, which introduces a slight performance trade-off.

@xstyled/system x 431,828 ops/sec ±1.06% (86 runs sampled)
styled-system x 549,224 ops/sec ±0.85% (90 runs sampled)
Fastest is styled-system

In v3, states are specified using object syntax, similar to how breakpoints are handled. States can be nested within breakpoints or other states.

States are configurable in the theme under the states key:

export const theme = {
  states: {
    hover: '&:hover',
    // ...
  },
}

// Basic state usage
<x.button color={{ _: 'red-500', hover: 'red-300' }} />

// Mixed screens and states
<x.button color={{ _: 'red-600', md: { _: 'red-500', hover: 'red-300' } }} />

// Nested states
<x.div bg={{ first: { odd: 'blue' } } } />

When using a function in the css prop with @xstyled/emotion, the signature and usage differ from standard Emotion:

1. The theme is accessed via a destructured object { theme }.
2. You must wrap your style object in the css function call.

With xstyled:

import { jsx } from '@xstyled/emotion'

const Button = ({ children }) => {
  return (
    <button
      css={({ theme }) =>
        css({
          paddingTop: theme.space[1],
        })
      }
    >
      {children}
    </button>
  )
}

/** @jsx jsx */
import { jsx } from '@xstyled/emotion'

const Button = ({ children }) => {
  return (
    <button
      css={({ theme }) =>
        css({
          paddingTop: theme.space[1],
        })
      }
    >
      {children}
    </button>
  )
}

xstyled automatically applies values defined in your theme.sizes section.

Important Note on Scales: Because values between 0 and 1 are reserved for fluid/percentage calculations, you must append a suffix s to target specific scale values from your theme. For example, a theme value of 0.5 must be referenced as 0.5s and 1 as 1s to avoid being treated as a percentage.

Example of using theme scales vs raw numbers:

<x.div maxHeight="1s" /> {/* Targets theme scale value 1 */}
<x.div maxHeight={8} />   {/* Sets fixed 8px */}

Values defined in the sizes section of your theme are automatically available. To avoid conflicts with fluid range values (0 to 1), you must append a suffix s to target theme values. For example, a theme value of 0.5 is accessed via 0.5s and 1 is accessed via 1s.

<x.div w="1s" />
<x.div w={8} />
<x.div w={12} />