Using styles

Once styles have been defined, they must be converted to className and styles props that can be spread on HTML elements using the stylex.props function.

<div {...stylex.props(styles.base)} />

While this is the simplest case, it is trivial to merge multiple style objects, use them conditionally, or even compose styles across module boundaries.

Merging styles

The stylex.props function can take a list of styles and merge them in a deterministic way, where the last style applied always wins. The order in which the styles are defined does not affect the resulting styles, only the order in which they are applied to the HTML element.

Using stylex.props is only required when styles are set on React DOM host elements like <div>.

Consider styles that are defined as follows:

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

const styles = stylex.create({
  base: {
    fontSize: 16,
    lineHeight: 1.5,
    color: 'grey',
  },
  highlighted: {
    color: 'rebeccapurple',
  },
});

<div {...stylex.props(styles.base, styles.highlighted)} />;

The resulting HTML element will have purple text, because that style was applied last. If instead the order of the styles were reversed, the text would be gray.

<div {...stylex.props(styles.highlighted, styles.base)} />

A simple way to think about the stylex.props function is that merges many objects and the later objects have precedence over previous objects.

Each individual style object can be passed to stylex.props as a separate argument, or passed in as an array of styles.

<div {...stylex.props([styles.base, styles.highlighted])} />

Conditional styles

Styles can be applied conditionally at runtime using common JavaScript patterns such as ternary expressions and the && operator. stylex.props ignores falsy values such as null, undefined, or false.

<div
  {...stylex.props(
    styles.base,
    props.isHighlighted && styles.highlighted,
    isActive ? styles.active : styles.inactive,
  )}
/>

Style variants

A common styling pattern called "variants" lets you apply styles based on the value of a specific prop, e.g., variant. StyleX supports this pattern without an additional API. Instead, an object property lookup can be used to achieve the same result.

First, each variant can be defined with the appropriate variant name for the style object.

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

const styles = stylex.create({
  violet: {
    backgroundColor: {
      default: 'blueviolet',
      ':hover': 'darkviolet',
    },
    color: 'white',
  },
  gray: {
    backgroundColor: {
      default: 'gainsboro',
      ':hover': 'lightgray',
    },
  },
  // ... more variants here ...
});

The appropriate styles can then be applied by using the variant prop as a key on the styles object.

function Button({variant, ...props}) {
  return <button {...props} {...stylex.props(styles[variant])} />;
}

Styles as props

StyleX encourages co-locating styles, but it's also possible to pass and use styles across file and component boundaries using component props.

Passing style props to components

When using custom components, styles created with StyleX can be passed down as props.

<CustomComponent style={styles.base} />

StyleX will correctly merge nested arrays of styles, which means you can use the same patterns described above to combine or conditionally apply styles.

<CustomComponent style={[styles.base, isHighlighted && styles.highlighted]} />

When combining local styles with styles passed in as props, it's idiomatic to apply the styles passed in as props after the local styles. Although, there's nothing wrong with applying certain local styles last, if you require them to always take priority over prop styles.

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

const styles = stylex.create({
  base: { /*...*/ }
});

function CustomComponent({style}) {
  return <div {...stylex.props(styles.base, style)} />;
}

In these examples the style prop name is arbitrary. You can use any prop name, just like when passing any other types of data to React components.

“Unsetting” styles

Sometimes, styles need to be removed rather than applied. While CSS provides values such as initial, inherit, unset, and revert, the simplest solution to do this in StyleX is to set the value to null.

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

const styles = stylex.create({
  base: {
    color: null
  },
});

Setting a style property to null removes any previously applied style for it by StyleX. And it doesn't result in additional generated CSS.