Compiled Documentation

Compiled is a compile-time CSS-in-JS library for React. It allows you to define styles using a styled API or a css prop, which are then extracted into an atomic stylesheet at build time to ensure high performance.

import { styled, ClassNames } from '@compiled/react';

// Tie styles to an element using the css prop
<div css={{ color: 'purple' }} />

// Create a styled component
const StyledButton = styled.button`
  color: ${(props) => props.color};
`;

// Use ClassNames for styles not tied to a specific element
<ClassNames>
  {({ css }) => children({ className: css({ fontSize: 12 }) })}
</ClassNames>

In the @compiled/webpack-loader/css-loader workflow, compiled-css.css serves as a placeholder CSS file used during the style extraction process. It fulfills two primary technical requirements:

1. Thread-safe collection of styles: It provides a centralized mechanism to collect styles safely across different threads or processes during the build.
2. Caching: It enables efficient caching of extracted styles, which results in faster build bundles.

The implementation details of how this file is utilized can be found in packages/webpack-loader/src/compiled-loader.ts.

Compiled automatically handles vendor prefixing for CSS declarations. You can write standard CSS properties in your style objects, and Compiled will convert them to standard CSS and then apply necessary auto-prefixes (e.g., -webkit-, -moz-, -ms-) to ensure cross-browser compatibility.

const styles = css({
  userSelect: 'none',
});

When using style composition (e.g., applying multiple css or cssMap objects to a component), the property ordering is applied across the entire composition. If a property in a later object in the array should have been overridden by a property in an earlier object based on Compiled's sorting, it will trigger a violation.

Example of violation in composition:

import { css, cssMap } from '@compiled/react';

const styles = cssMap({
  root: {
    paddingTop: '5px',
  },
  warning: {
    // ...
  },
});

const extraPadding = css({
  padding: '5px',
});

const Component = ({ children }) => {
  // Violation: paddingTop is applied before padding, but Compiled sorts padding to be overridden by paddingTop
  return <div css={[styles.root, extraPadding]}>{children}</div>;
};

To migrate to a new hashing scheme that prevents class name collisions, set collisionResistantHash: true.

• Legacy (Default): Uses a base-36 hash (9-character class names: _ + 4-char group + 4-char value).
• New (Migration): Uses a base-62 encoded, zero-padded hash (11-character class names: _ + 6-char group + 4-char value).

Important: This option requires @compiled/react@>=1.0.0. The runtime ax() can handle both formats simultaneously, allowing you to mix old and new classes on the same page during a migration (e.g., when consuming CSS from different npm packages).

Passing dynamic styling or props directly to Compiled is no longer recommended because it can interfere with the static analysis used by Atlassian tooling.

To handle dynamic styles, follow these recommendations in order of preference:

1. Rewrite as conditional rules or cssMap: Determine if the dynamic style can be expressed as a set of static conditional rules or by using cssMap.
2. Use the style prop: If you absolutely require dynamic styling that cannot be statically determined, pass the styles to the standard HTML style prop instead of the Compiled css prop.

For more details on the preferred approach, refer to the UI Styling Standard.