CSS-in-JS

What it is and why it exists

CSS-in-JS is a family of techniques in which application code declares styles and a library or compiler produces CSS. The authoring form might be a tagged template, a JavaScript object, a function of component props, or a typed recipe. The browser still receives CSS declarations, selectors, and values; JavaScript is the authoring and delivery mechanism, not a replacement for CSS.

The approach gives a component an explicit dependency on its styles. Generated class names reduce accidental selector collisions, while ordinary imports make it easier to remove a component and the styles used only by that component. A JavaScript boundary also makes component state, theme tokens, and variants available to the styling layer.

You meet CSS-in-JS most often in component libraries and React applications, but the label covers different execution models. A runtime library creates or selects rules while components render. A build-time system analyzes source files and emits CSS assets before deployment. Some tools combine extraction with a small runtime for values that cannot be known during the build.

That distinction matters more than template syntax. It decides which expressions are legal, how much styling code reaches the client, when rules become available, and what server rendering must collect. Treat “CSS-in-JS” as a design space, not as one API with one performance profile.

Use it when component ownership, typed tokens, or a programmatic variant API removes real coordination work. Plain stylesheets, CSS Modules, Sass, and utility classes remain reasonable when the cascade already expresses the design cleanly. Co-location is useful, but it is not enough by itself to justify a runtime dependency.

How it works

Every implementation must connect an authored style description to a browser-visible rule. The main choice is whether that connection happens during rendering or during compilation.

Runtime generation

A runtime engine reads a style declaration when a component is created or rendered. It serializes the declaration, derives an identifier, checks a cache, and inserts a rule into a stylesheet when necessary. The component receives the corresponding class name. Libraries differ in when they do each step, so inspect the library’s output rather than assuming every render creates a new <style> element.

Style injection is the act of adding generated rules to a document or server-side style collector. Caching is important because the same normalized style should reuse a rule. Interpolations based on props may create more rule combinations, especially when the input has many possible values.

Runtime generation can evaluate arbitrary application state. That flexibility is useful for values that genuinely depend on live JavaScript, but it also ties style availability to the component lifecycle. The library’s server-rendering integration must collect the same rules that the client expects.

Build-time extraction

With static extraction , a compiler evaluates supported declarations during the build and writes ordinary CSS. Application code imports generated class names or calls an API whose possible results the compiler understands. The browser downloads the emitted stylesheet without needing a client-side rule generator for those declarations.

Extraction imposes an analyzability boundary. Literal objects, tokens, and finite variant maps are straightforward inputs. A value obtained from a request, browser measurement, or arbitrary runtime function cannot be turned into one fixed rule during the build. Tools handle that boundary with CSS custom properties, inline styles, predeclared variants, or a documented runtime layer.

“Zero runtime” describes the styling system’s rule-generation path, not the entire application. Extracted CSS still has transfer, parse, cascade, style calculation, layout, and paint costs. The useful claim is narrower: static declarations do not require that library to generate rules in the browser.

The cascade still decides the result

Both paths end in the CSS cascade. A unique class reduces name collisions, but normal origin, layer, importance, specificity, scoping proximity, and source-order rules still choose the winning declaration. Global selectors can affect generated elements, and generated selectors can override other styles.

Insertion order becomes part of behavior when selectors have equal priority. Code splitting, streaming, multiple caches, or mixing styling systems can change that order if the integration does not define it. Cascade layers and a documented style insertion point are more reliable than escalating specificity until a test happens to pass.

Discrete state and continuous values

Finite states such as tone="danger", size="small", and disabled work well as predeclared classes or data-attribute selectors. Their set is bounded, so a compiler can emit every rule and a runtime engine can reuse a small cache. This also makes unsupported states visible to types and tests.

Values such as a drag coordinate, color-picker result, or progress percentage have a large or unbounded domain. Generating a class for every value grows the rule set and asks the styling engine to repeat work. Keep the structural rule stable and pass the changing value through a validated CSS custom property or inline style.

Examples

These examples expose the mechanics with small, dependency-free programs. They are teaching models, not APIs to copy into production; a maintained library must also parse nested selectors, at-rules, escaping, prefixes, concurrency, and server integration.

Hashing and caching one runtime rule

The first model normalizes an object, hashes the resulting declaration string, and caches the rule by class name. Sorting properties makes object insertion order irrelevant. The second call returns the same class without adding another entry.

Production engines need collision handling and a complete CSS serializer; this tiny hash has neither. The useful observation is the data flow: equivalent declarations need a stable identity and a shared cache. If the server and client normalize differently, the class identity can diverge even when the intended CSS looks the same.

Selecting finite variants

A build-time recipe can emit a bounded set of classes and leave runtime code to select among them. This plain JavaScript model validates both axes instead of silently falling back when generated code invents a variant name.

const buttonRecipe = {
  base: "button",
  tone: {
    primary: "button_tone_primary",
    quiet: "button_tone_quiet",
  },
  size: {
    small: "button_size_small",
    medium: "button_size_medium",
  },
};

function buttonClass({ tone = "primary", size = "medium" } = {}) {
  const toneClass = buttonRecipe.tone[tone];
  const sizeClass = buttonRecipe.size[size];
  if (!toneClass || !sizeClass) throw new RangeError("unknown button variant");
  return [buttonRecipe.base, toneClass, sizeClass].join(" ");
}

console.log(buttonClass());
console.log(buttonClass({ tone: "quiet", size: "small" }));

try {
  buttonClass({ tone: "warning" });
} catch (error) {
  console.log(`${error.name}: ${error.message}`);
}

button button_tone_primary button_size_medium
button button_tone_quiet button_size_small
RangeError: unknown button variant

Real recipe tools often generate these names and TypeScript types together. The important boundary is still visible here: the CSS covers a finite state space, while runtime code only chooses a valid combination. A design-system component should document defaults and invalid combinations instead of accepting arbitrary strings.

Passing a continuous value

Progress can change to many values, so it should not require a new class at every update. One stable rule reads --progress; application code clamps the input and sets only that custom property. The same numeric value also drives the accessibility state.

function progressProps(input) {
  const value = Math.min(100, Math.max(0, Number(input)));
  if (!Number.isFinite(value)) throw new TypeError("progress must be numeric");

  return {
    className: "progress",
    style: { "--progress": `${value}%` },
    "aria-valuenow": value,
  };
}

const rule = ".progress { inline-size: var(--progress); }";
console.log(rule);

for (const input of [-15, 45, 120]) {
  console.log(JSON.stringify(progressProps(input)));
}

.progress { inline-size: var(--progress); }
{"className":"progress","style":{"--progress":"0%"},"aria-valuenow":0}
{"className":"progress","style":{"--progress":"45%"},"aria-valuenow":45}
{"className":"progress","style":{"--progress":"100%"},"aria-valuenow":100}

TypeScript can describe the custom-property key, but a type annotation does not clamp a runtime value or attach a unit. Validation belongs where untrusted or loosely typed data enters the component. The CSS should also provide a fallback when the property may be absent.

Collecting deterministic server styles

Server rendering needs the HTML and the rules used by that render. This model collects finite variant rules in a request-local registry, deduplicates by class name, and sorts before serialization. A real integration may preserve a different defined order, especially when order carries cascade meaning.

function createStyleRegistry() {
  const rules = new Map();

  return {
    use(className, cssText) {
      rules.set(className, `.${className}{${cssText}}`);
      return className;
    },
    flush() {
      return [...rules.entries()]
        .sort(([left], [right]) => left.localeCompare(right))
        .map(([, rule]) => rule)
        .join("\n");
    },
  };
}

function renderCard(registry, tone, label) {
  const variants = {
    neutral: ["card-neutral", "background:#f3f4f6;color:#111827"],
    urgent: ["card-urgent", "background:#fee2e2;color:#991b1b"],
  };
  const selected = variants[tone];
  if (!selected) throw new RangeError("unknown card tone");
  const className = registry.use(...selected);
  return `<article class="${className}">${label}</article>`;
}

const registry = createStyleRegistry();
const html = [
  renderCard(registry, "urgent", "Retry payment"),
  renderCard(registry, "neutral", "Receipt ready"),
].join("");

console.log(html);
console.log(registry.flush());

<article class="card-urgent">Retry payment</article><article class="card-neutral">Receipt ready</article>
.card-neutral{background:#f3f4f6;color:#111827}
.card-urgent{background:#fee2e2;color:#991b1b}

The registry is created per render so concurrent requests do not leak rules into one another. Its output order is deterministic for this model, and repeated uses of a class overwrite the same map entry. Framework integrations add streaming, nonce handling, cache adoption, and cleanup rules that this example intentionally omits.

Pitfalls

Declaring styled components during render

React can remount the subtree, which loses focus, selection, uncontrolled input state, and local component state. The styling library may also repeat registration work. This is a correctness problem before it is a micro-optimization.

Fix: declare stable styled components at module scope. If a style depends on props, pass the prop to a module-scoped declaration or select a predeclared variant. Verify identity with a focus-preservation test instead of relying on a visual snapshot.

Generating a class for every live value

The exact cache behavior depends on the library, so there is no universal threshold at which this becomes slow. The smell is semantic: the value is instance data with a broad domain, while a class represents a reusable style category.

Fix: use finite classes for states and variants. Put high-cardinality values in validated CSS custom properties or inline styles, then record a browser performance trace if the update path matters.

Forwarding styling-only props to the DOM

This can produce invalid markup, React warnings, misleading DOM snapshots, or accidental string attributes. Different libraries use transient-prop conventions or prop-filter callbacks, and the details are not interchangeable.

Fix: follow the selected library’s documented filtering mechanism and inspect the rendered DOM. Prefer data-* or ARIA attributes only when the value has real DOM semantics; do not rename every leaked prop to data-* merely to suppress a warning.

Assuming generated classes escape the cascade

Adding !important or nesting selectors until the generated rule wins makes ownership harder to understand. It can also break consumers that need a supported override point.

Fix: define the component’s override contract, put style systems into deliberate cascade layers or insertion points, and inspect computed styles when rules conflict. Test the application shell and third-party content together because isolation claims fail at their boundaries.

Treating server integration as a copy-paste detail

Random values, locale-dependent serialization, browser-only branches, a shared global registry, and misordered streaming flushes can all make output nondeterministic. Support also varies by library and version, including React Server Component behavior.

Fix: use the library’s current integration for the chosen framework and rendering mode. Compare server HTML and style output across repeated renders, test hydration with warnings treated as failures, and verify that the first rendered screen remains styled with JavaScript delayed.

Hiding runtime expressions from an extractor

Generated code often looks plausible because its styling call type-checks, yet the production CSS lacks the corresponding rule. Development behavior may differ if a plugin or watcher scans a wider set of files.

Fix: keep extractable declarations in the syntax and file set documented by the tool. Run a production build, search the emitted CSS for each important variant, and test a value that is not the default. Route truly runtime data through the tool’s supported variable or inline-style escape hatch.

In the AI era

Use an agent to run a migration spike on one stateful, server-rendered component before changing the whole styling system. It can port the component with the versions in the lockfile, route continuous values through CSS custom properties, and compare the production result with the existing rendering contract: CSS in the first response, stable class identifiers across repeated renders, clean hydration, filtered DOM props, computed styles, and supported overrides. If the spike preserves that contract, the same transformation can expand to similar components; if it does not, the emitted HTML and CSS provide a concrete reason to revise or reject the migration.

Further reading

• W3C: CSS Cascading and Inheritance Level 6
• W3C: CSS Object Model
• MDN: CSS custom properties