Using styles

Once styles have been defined, they can be converted to props that can be spread on HTML elements using the stylex.props function. The stylex.props function sets the appropriate className prop on the HTML element and, when using dynamic styles, the style prop.

<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 merges them in a deterministic way, where “the last style applied always wins”.

Consider that a couple of style objects are defined as so:

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. Instead, if the order of the styles were reversed, the text would be gray.

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

Note: 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.

Like Object.assign

A simple way to think about the stylex.props function is that it does what Object.assign does. It merges many objects and the later objects have precedence over previous objects.

The actual implementation is optimized for performance.

Conditional styles

Styles can be applied conditionally at runtime by 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 one of a list of possible styles based on the value of the prop named 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 ...
});

Then, the appropriate styles can 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

Although StyleX encourages co-locating styles, it is possible to pass and use styles across file and component boundaries. It is idiomatic to pass override styles to a component as props.

Passing style props to components

<CustomComponent style={styles.base} />

danger

Don't use the stylex.props functions when passing styles to a custom component.

// NO!
<CustomComponent {...stylex.props(styles.base)} />

// NO!
<CustomComponent style={stylex.props(styles.base)} />

The stylex.props function should only be used directly on HTML elements.

Multiple style objects, including conditional styles, can be passed in using an array literal:

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

Prop names are arbitrary

style is an arbitrary prop name. You can choose your own prop names for your codebase.

Accepting styles in components

Accepting custom StyleXStyles is as simple as accepting any other prop. and applying it with the stylex.props function. Just like local styles.

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

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

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

It is idiomatic to apply styles passed in as props after the local styles. This convention makes design system components predictable to use and easy to customize.

“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.