How Styled-Components Works Under the Hood and Building a Minimal CSS‑in‑JS Library

Preface

The author recently learning Material UI discovered that its components are built with CSS‑in‑JS, which sparked curiosity about how CSS‑in‑JS libraries operate and why Material UI chose this approach, leading to an exploration and the creation of a personal CSS‑in‑JS library.

Research

Two popular CSS‑in‑JS libraries are emotion and styled-components. Their APIs are largely identical, but the author abandoned emotion due to its mixed JavaScript, Flow, and TypeScript source, and selected styled-components as the study target.

styled-components Core Capabilities

Usage

Opening the official documentation, navigating to Documentation → API Reference, the first core API shown is styled. Example usage with template literals:

const Button = styled.div`
  background: palevioletred;
  border-radius: 3px;
  border: none;
  color: white;
`;

This creates a React component with embedded styles.

Digging Deeper

Cloning the GitHub repo reveals that styled-components is a monorepo; the core package shares the repo name. The default export styled originates from src/constructors/styled.tsx.

Inspecting src/constructors/styled.tsx, the simplified code is:

import createStyledComponent from '../models/StyledComponent';
import domElements from '../utils/domElements';
import constructWithOptions from './constructWithOptions';

const baseStyled = (tag) => constructWithOptions(createStyledComponent, tag);
const styled = baseStyled;

domElements.forEach(domElement => {
  styled[domElement] = baseStyled(domElement);
});

export default styled;

The styled API essentially provides a shortcut styled[HTMLElement] for rapid component creation.

Core Source

The constructWithOptions factory returns a template function that invokes the component constructor with CSS processing. Simplified:

export default function constructWithOptions(componentConstructor, tag, options) {
  const templateFunction = (initialStyles, ...interpolations) =>
    componentConstructor(tag, options, css(initialStyles, ...interpolations));
  return templateFunction;
}

Thus baseStyled is built by this factory.

Further up the chain, the component constructor is createStyledComponent, which returns a WrappedStyledComponent created with React.forwardRef and utilizes the hook useStyledComponentImpl.

The hook useInjectedStyle creates a