CSS-in-JavaScript

Relevant source files

• css-in-javascript/README.md
• linters/.markdownlint.json
• package.json

Purpose and Scope

This document details the Airbnb CSS-in-JavaScript style guide, defining patterns for writing styles as JavaScript objects. These conventions are optimized for the react-with-styles abstraction layer, which facilitates theming, runtime style injection, and implementation-agnostic styling.

For React component structure and JSX syntax, refer to React Component Structure and JSX Formatting and Syntax For general JavaScript naming conventions, see Code Style and Formatting

Overview

Airbnb utilizes a CSS-in-JS approach where styles are defined as JavaScript objects and processed by a higher-order component (HOC). This allows for dynamic theming using shared variables and reduces coupling to specific underlying CSS implementations.

CSS-in-JS Architecture

Diagram: CSS-in-JS Pattern Flow - Illustrates the transformation of style objects into rendered DOM attributes via withStyles() and css().

Sources: css-in-javascript/README.md1-11 css-in-javascript/README.md259-264

Style Definition Pattern

Component and Style Ordering

Styles must be defined after the component definition. This pattern reduces indirection by passing the style object directly to the withStyles() HOC in the export statement.

Diagram: Component Export Pattern - The recommended structure for defining themed styles alongside components.

Pattern Element	Location	File Reference
Component definition	Before export	css-in-javascript/README.md180-187
withStyles() call	Export statement	css-in-javascript/README.md189-193
css() helper	Inside JSX	css-in-javascript/README.md182

Sources: css-in-javascript/README.md154-194

Naming Conventions

Selector Naming

• camelCase: Use camelCase for object keys (selectors) because they are accessed as properties on the styles object css-in-javascript/README.md13-33
• Modifiers: Use an underscore (_) for modifiers to other styles (e.g., bruceBanner_theHulk). This follows BEM-like logic without requiring quoted keys css-in-javascript/README.md35-63
• Fallbacks: Use the _fallback suffix for sets of fallback styles to maintain a clear relationship with the primary selector css-in-javascript/README.md65-91

Breakpoint Naming

Use device-agnostic names rather than device-specific names (e.g., "small" instead of "phone").

Category	Recommended	Avoid
Size	small, medium, large	mobile, tablet, desktop

Sources: css-in-javascript/README.md134-152

Theming System

Theming is managed through an abstraction layer like react-with-styles. Components should never hardcode values that belong in a theme.

Core Theme Properties

Diagram: Theme Property System - Centralized design tokens registered via ThemedStyleSheet.

• Colors: Define colors only in themes to ensure consistency and easy refactoring css-in-javascript/README.md265-281
• Fonts: Fonts should be defined as complete style sets in the theme css-in-javascript/README.md283-320
• Grid Units: Use a base unit (typically 8px) and multipliers for spacing css-in-javascript/README.md322-345
• Fallbacks: Use theme-provided helpers like fallback() or a fallbacks object to handle property collisions during object merging css-in-javascript/README.md373-410

Sources: css-in-javascript/README.md259-410

Style Organization

Nesting and Whitespace

Leave a blank line between adjacent blocks at the same indentation level to improve readability and minimize merge conflicts css-in-javascript/README.md196-230

Inline vs Themed Styles

• Themed Styles: Use for low cardinality styles (fixed sets). Generating themed stylesheets is expensive css-in-javascript/README.md234-236
• Inline Styles: Use for high cardinality styles, such as those derived directly from props (e.g., a dynamic margin value) css-in-javascript/README.md234-236

Sources: css-in-javascript/README.md247-251

Summary Table

Concept	Rule	Source
Key Casing	Use camelCase for selectors	css-in-javascript/README.md15-17
Modifiers	Use _ (underscore) for variations	css-in-javascript/README.md35-37
Placement	Define styles after component	css-in-javascript/README.md156-159
Colors	Must be defined in theme	css-in-javascript/README.md265-266
Spacing	Use theme unit or units()	css-in-javascript/README.md322-323

Sources: css-in-javascript/README.md1-433