facebook
@stylexjs/stylex
StyleX is a JavaScript library for defining styles for optimized user interfaces.
Installation
To start playing with StyleX without having to set up any build settings you can install just two packages:
npm install --save @stylexjs/stylexCompiler
StyleX is designed to extract styles to a static CSS style sheet during an app's build process. StyleX provides a Babel plugin along with plugin integrations for Webpack, Rollup and NextJS.
npm install --save-dev @stylexjs/babel-pluginFor more information on working with the compiler, please see the documentation
for
@stylexjs/babel-plugin.
API
stylex.create()
Styles are defined as a map of CSS rules using stylex.create(). In the example
below, there are 2 different CSS rules. The names "root" and "highlighted" are
arbitrary names given to the rules.
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
root: {
width: '100%',
color: 'rgb(60,60,60)',
},
highlighted: {
color: 'yellow',
},
});Pseudo-classes and Media Queries can be nested within style definitions:
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
root: {
width: '100%',
color: 'rgb(60,60,60)',
maxWidth: {
'@media (min-width: 800px)': '800px',
},
},
highlighted: {
color: 'yellow',
opacity: {
':hover': '0.9',
},
},
});The compiler will extract the rules to CSS and replace the rules in the source code with a "compiled style" object.
stylex.props()
Applying style rules to specific elements is done using stylex.props. Each
argument to this function must be a reference to a compiled style object, or an
array of compiled style objects. The function merges styles from left to right.
<div {...stylex.props(styles.root, styles.highlighted)} />The stylex.props function returns React props as required to render an
element. StyleX styles can still be passed to other components via props, but
only the components rendering host platform elements will use stylex.props().
For example:
const styles = stylex.create({
internalRoot: {
padding: 10,
},
exportedRoot: {
position: 'relative',
},
});
function InternalComponent(props) {
return (
<div {...props} {...stylex.props(styles.internalRoot, props.style)} />
);
}
export function ExportedComponent(props) {
return <InternalComponent style={[styles.exportedRoot, props.style]} />;
}Styles can be conditionally included using standard JavaScript.
<div {...stylex.props(styles.root, isHighlighted && styles.highlighted)} />And the local merging of styles can be used to control the relative priority of rules. For example, to allow a component's local styles to take priority over style property values passed in via props.
<div {...stylex.props(props.style, styles.root)} />stylex.firstThatWorks()
Defining fallback styles is done with stylex.firstThatWorks(). This is useful
for engines that may not support a specific style property.
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
header: {
position: stylex.firstThatWorks('sticky', '-webkit-sticky', 'fixed'),
},
});This is equivalent to defining CSS as follows:
.header {
position: fixed;
position: -webkit-sticky;
position: sticky;
}Types
StyleX comes with full support for Static Types.
StyleXStyles<>
The most common type you might need to use is StyleXStyles<>. This lets you accept
an object of arbitrary StyleX styles.
type Props = {
...
style?: StyleXStyles<>,
};
function MyComponent({style, ...}: Props) {
return (
<div {...stylex.props(localStyles.foo, localStyles.bar, style)} />
);
}StyleXStylesWithout<>
To disallow specific style properties, use the StyleXStylesWithout<> type.
type Props = {
// ...
style?: StyleXStylesWithout<{
position: unknown;
display: unknown;
}>;
};StaticStyles<>
To constrain the styles to specific properties and values, use the StaticStyles<>
type. For example, if a component
should accept marginTop but only accept one of 0, 4, or 8 pixels as
values.
type Props = {
...
style?: StaticStyles<{
marginTop?: 0 | 4 | 8;
}>,
};How StyleX works
StyleX produces atomic styles, which means that each CSS rule contains only a single declaration and uses a unique class name. For example:
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
root: {
width: '100%',
color: 'red',
}
}From this code, StyleX will generate 2 classes. One for the width: '100%'
declaration, and one for the color: 'red' declaration. If you use the
declaration width: '100%' anywhere else in your application, it will reuse
the same CSS class rather than creating a new one.
One of the benefits of this approach is that the generated CSS file grows logarithmically as you add new styled components to your app. As more style declarations are added to components, they are more likely to already be in use elsewhere in the app. As a result of this CSS optimization, the generated CSS style sheet for an app is usually small enough to be contained in a single file and used across routes, avoiding style recalculation and layout thrashing as users navigate through your app.