Skip to main content

Introduction to StyleX

StyleX is a simple, easy-to-use JavaScript syntax and compiler for styling web apps.

StyleX combines the strengths and avoids the weaknesses of both inline styles and static CSS. Defining and using styles requires only local knowledge within a component, and avoids specificity issues while retaining features like Media Queries. StyleX builds optimized styles using collision-free atomic CSS which is superior to what could be authored and maintained by hand.

Features at a glance​

Scalable​

  • Minimize CSS output with atomic CSS.
  • The CSS size plateaus even as the number of components grows.
  • Styles remain readable and maintainable within growing codebases.

Predictable​

  • Class names on an element can only directly style that same element.
  • No specificity issues.
  • “The last style applied always wins!”

Composable​

  • Apply styles conditionally.
  • Merge and compose arbitrary styles across component and file boundaries.
  • Use local constants and expressions to keep styles DRY. Or repeat styles without worrying about performance.

Fast​

  • No runtime style injection.
  • All styles are bundled in a static CSS file at compile-time.
  • Optimized runtime for merging class names.

Type-Safe​

  • Type-safe APIs.
  • Type-safe styles.
  • Type-safe themes.

Using StyleX​

Configure the compiler​

import plugin from '@stylexjs/rollup-plugin';

const config = () => ({
  plugins: [
    plugin({ ...options })
  ]
})

export default config;

Define styles​

Styles are defined using an object syntax and the create() API.

import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
  root: {
    width: '100%',
    maxWidth: 800,
    minHeight: 40,
  },
});

Any number of rules can be created by using additional keys and additional calls to create():

import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
  root: {
    width: '100%',
    maxWidth: 800,
    minHeight: 40,
  },
  child: {
    backgroundColor: 'black',
    marginBlock: '1rem',
  },
});

const colorStyles = stylex.create({
  red: {
    backgroundColor: 'lightred',
    borderColor: 'darkred',
  },
  green: {
    backgroundColor: 'lightgreen',
    borderColor: 'darkgreen',
  },
});

Use styles​

To use styles they must be passed to the props() function. Styles can be combined and applied conditionally using standard JavaScript expressions.

import * as React from 'react';
import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({ ... });

function ReactDiv({ color, isActive, style }) {
  return <div {...stylex.props(
    styles.main,
    // apply styles conditionally
    isActive && styles.active,
    // choose a style variant based on a prop
    colorStyles[color],
    // styles passed as props
    style,
  )} />;
}

The example above uses JSX. StyleX itself is framework agnostic. The same code works with other frameworks that accept className strings and style objects such as SolidJS, Preact or Qwik.

Ideal use cases​

StyleX works well in a wide variety of projects. However, it was designed to meet the challenges of particular use cases.

Authoring UI in JavaScript​

StyleX is a CSS-in-JS library, which means that it is most useful when an app's UI is authored in JavaScript. If an application uses a framework like React, Preact, Solid, lit-html, or Angular, using StyleX should be a good fit.

Some frameworks, such as Svelte and Vue use custom file formats that are compiled to JavaScript at build time. StyleX can still be used in these frameworks, but may need some custom configuration.

Large or growing projects​

While StyleX works well for projects of all sizes, it really shines in larger applications.

Since StyleX compiles to atomic class names, a big performance benefit is that the size of the CSS bundle plateaus as a project grows.

Reusable components​

The benefits of StyleX are greatest when used alongside reusable UI components.

For years, we have had to choose between "Design System" components that come with styles baked in but can be difficult to customize or "Headless" components that are completely unstyled.

StyleX empowers developers to build UI components that can have default styles and still be customizable.

Further, the consistency enables sharing these components by publishing them to NPM. As long as the consumer of a component is also using StyleX, the styles will be merged and composed correctly without any additional configuration.