CSS-in-JavaScript
Relevant source files
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.
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
stylesobject 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
_fallbacksuffix 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 afallbacksobject 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
marginvalue) css-in-javascript/README.md234-236
Sources: css-in-javascript/README.md247-251
Summary Table
Sources: css-in-javascript/README.md1-433
Refresh this wiki