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.

React

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

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

function Box({ 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,
  )} />;
}

Solid

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

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

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

Qwik

import { component$ } from '@builder.io/qwik';
import * as stylex from '@stylexjs/stylex';

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

const Box = component$(({ 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,
  )} />;
})

Svelte 5

<script context="module">
  import * as stylex from '@stylexjs/stylex';

  const styles = stylex.create({ ... });
</script>
<script>
  import { spread } from './helpers';
  let { color, isActive, style } = $props();
</script>

<div {...spread(
  stylex.props(styles.main,
    isActive && styles.active,
    colorStyles[color],
    style
  )
)}>
  Hi!
</button>

When a frameworks accepts a className string and a style object, the stylex.props() function call can be spread directly to apply styles. For other frameworks, a helper function may be needed.

Ideal use cases

StyleX works well in a wide variety of projects. However, it was designed to meet the challenges of particular uses 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.