skip to content

With CSS Modules, a file declares `.book-card` but `className={styles.bookCard}` leaves the element unstyled without any error — why, and what fixes it?

level: middleimportance: should knowfreq 18%

answer

  1. plain object, missing key
  2. keys are authored names by default
  3. camelCase conversion is configured
  4. bracket access for dashed names
  5. global names absent from map

basics

~10 s

The class map is a plain object whose keys are the names as written, so styles.bookCard is undefined unless the toolchain converts keys to camelCase. Use styles['book-card'], rename the class, or enable key conversion.

solid answer

~40 s

A CSS Modules import is a **plain object of strings**, and in common setups its keys are the class names exactly as written — `book-card`, not `bookCard`. Reading a key that is not there returns `undefined`, which throws nothing: in JSX `className={undefined}` simply renders no class, and in a template string it becomes the text `undefined`. Fixes: read `styles['book-card']`, rename the class to `.bookCard` (the CSS Modules docs recommend camelCase local names), or turn on the toolchain's camelCase key convention — noting that the variant which *drops* the original key breaks every existing `styles['book-card']`. The same silent `undefined` comes from a typo, from a class written only inside `:global(...)` and from a class declared in a different module.

code

tsx · 14 lines
tsx
/* BookCard.module.css declares .book-card and .cover */
import styles from './BookCard.module.css';

export function BookCard({ title }: { title: string }) {
  return (
    // styles.bookCard is undefined unless keys are camelCased:
    // the div renders with no class and no error.
    <div className={styles.bookCard}>
      {/* bracket access matches the default keys */}
      <div className={styles['book-card']}>{title}</div>
      <img className={styles.cover} alt="" />
    </div>
  );
}

go deeper

for a junior

Recall that the import is a plain object, so a key that is not there is undefined and the element just renders without its class.

for a middle

Explain where keys come from — the authored names, plus whatever conversion the toolchain is configured with — and list the other silent-miss causes: typos, globals, the wrong module.

for a senior

Show how you would make this failure loud across a codebase: typed imports, one naming rule, a development-time guard, and care when changing the key convention.

for a principal

Decide a naming rule and key convention once for every package that ships modules, since a convention change silently breaks bracket lookups in consumers you do not build.

## Why nothing fails The value a CSS Modules import gives you is a **class map**: an ordinary JavaScript object from authored names to generated names, built at compile time. Property access on an ordinary object never throws for a missing key — it evaluates to `undefined`. So the failure is completely silent: - in JSX, `className={undefined}` renders the element **without a class attribute**; - in a template string, `` `${styles.bookCard} active` `` produces the literal class `undefined active`; - the CSS rule for the real generated name is in the page the whole time, matching nothing. The element looks unstyled, the console is clean and the build is green. Static typing can catch the misspelling, but that is a declaration concern layered on top; at runtime the map is just an object. ## What the keys are, by default The CSS Modules naming guide recommends **camelCase local names** precisely because kebab-case names cannot be read with dot notation: `styles.class-name` is a subtraction, so you must write `styles['class-name']`. Whether keys are converted depends on the toolchain's **key convention**, which is configured, not intrinsic: | Toolchain (examples) | Default keys for `.book-card` | |---|---| | The `postcss-modules` transform (and tools that pass options to it, such as Vite) | `book-card` only — no conversion | | webpack's css-loader 7 with named exports on | `book-card` as written | | webpack's css-loader with named exports off | `bookCard` only — original removed | So the same component can work under one build and render unstyled under another. ## The conventions, as rules The common conventions behave like this for `.cover-flip`: 1. **Keep as written** — only `cover-flip`. 2. **camelCase** — both `cover-flip` and `coverFlip`. 3. **camelCase only** — only `coverFlip`; `styles['cover-flip']` now returns `undefined`. 4. **Dashes / dashes only** — like the two above, but only the dashes in a name are camelized. Switching a codebase from (1) to (3) is therefore a breaking change for every bracket access, and switching from (2) to (3) breaks every lookup that used the original name. ## Other ways to get `undefined` - **A typo** — `styles.bookCrad`. - **A global name** — a rule written `:global(.is-modal-open)` keeps its plain name and, by default, does **not** appear in the map at all; apply the literal string instead. - **The wrong module** — `.badge` lives in `Badge.module.css`, but the component imported `BookCard.module.css`; the generated name exists only in the other file's map. - **The wrong import shape** — css-loader 7.0.0 made `modules.namedExport` default to `true` when ES modules output is on; its migration guide replaces `import style from './style.css'` with `import * as style from './style.css'`. Code written for the earlier default can end up reading keys from something that is not the class map. ## Finding it in the browser 1. **Inspect the element.** No `class` attribute at all, or a class literally called `undefined`, points at the lookup, not at the CSS. 2. **Log the map.** `console.log(styles)` shows the real keys — `book-card` instead of `bookCard` answers the question in one line. 3. **Search the emitted CSS** for the generated name the map does hold; if the rule is there, the stylesheet is fine and only the JavaScript side is wrong. 4. **Check the import shape** if the logged value is not an object of names at all. ## How to make the failure loud - **Type the import** so unknown keys fail compilation (a declaration-file concern, handled elsewhere). - **Prefer one naming rule** — camelCase class names in every module make the key convention irrelevant. - **Wrap the map in development** with a `Proxy` that warns on a missing key, if your team keeps hitting this. - **Test what the user sees**, not class names: a visual or accessibility check catches an unstyled element that a snapshot of class strings would bless. ## Handing values, not just class names The map is built from an ICSS `:export` block, and you can add your own: `:export { coverWidth: 180px; }` makes `styles.coverWidth` the string `180px`. Several `:export` blocks are merged, and a duplicated key takes the last value in source order — another place where a quiet overwrite, not an error, is the failure mode.

  • How can a CSS Modules file hand a non-class value, such as a cover width, to JavaScript?
    Add an ICSS `:export` block: `:export { coverWidth: 180px; }`. The key joins the same object as the class names, and the value arrives as a literal string. Several blocks merge, and a duplicated key keeps the last one in source order.
  • Your team turns on a camel-case-only key convention to allow `styles.bookCard`; what breaks?
    Every existing `styles['book-card']` lookup, because that convention removes the original key from the map. Each now returns `undefined` silently, so the change needs a search for bracket access before it ships, or the convention that keeps both keys.

  • A misspelt class-map key makes the build fail.
  • CSS Modules always convert kebab-case class names to camelCase keys.
  • Classes written with `:global` appear in the class map by default.
  • `className={undefined}` makes the framework throw at render time.
  • Dot notation works for kebab-case keys like `styles.book-card`.