In CSS Modules, how does `composes` let a Button module's `.primary` reuse `.base`, and what rules limit where and how `composes` may be written?
answer
- reuse by adding classes
- map value lists several names
- single local class selector
- same file, `from` a file, `from global`
- cross-file order undefined
basics
~20 scomposes copies no declarations: it makes the class map's value for .primary list both generated names, so the element carries both classes. It works only on a single local class selector, before other declarations, and cross-file order is undefined.
solid answer
~50 s`composes: base;` inside `.primary` tells the transform to export `.primary` as **two** generated names, `"Button_base__a1 Button_primary__b2"`, so the element gets both classes and both rules apply — no declarations are copied. It can reuse a class from the same file, from another module (`composes: base from './Button.module.css'`) or a global class (`composes: sr-only from global`), and can list several. The limits: the rule's selector must be a **single local class name** (not `.a .b`, `.a:hover` or an ID), `composes` lines must come **before** the other declarations (the spec's rule), the referenced class must exist, and composition must not be circular. Because both classes apply separately, which declaration wins is ordinary cascade: same-file order follows the source, and between files the docs call the order **undefined** — so never set one property in classes composed from different files.
code
css · 18 lines/* Button.module.css */
.base {
padding: 0.5rem 1rem;
border-radius: 4px;
}
.base:hover { filter: brightness(1.1); }
.primary {
composes: base; /* same file, before other declarations */
background: navy;
}
/* BookCard.module.css */
.reserve {
composes: base from './Button.module.css';
composes: sr-hint from global;
margin-top: 0.75rem; /* never redefine padding here */
}go deeper
Recall that composes reuses another class by giving the element both classes, and that it can pull from the same file, another module or a global class.
Explain the map value as a list of generated names, the single-local-class and before-other-declarations rules, and why hover rules come along.
Diagnose override bugs: equal specificity means emitted order decides, which is undefined across files, so overlapping properties must live in one file.
Set the composition policy for a shared library: hierarchical bases and variants, no cross-file overlap of properties, and when two classes at the call site are clearer.
## What `composes` does In a CSS Module, `composes` is a pseudo-declaration that the transform removes from the output. Instead of copying declarations into the rule, it changes what the **class map** exports for that class: ```css /* Button.module.css */ .base { padding: 0.5rem 1rem; border-radius: 4px; } .primary { composes: base; background: navy; color: white; } ``` The map's entry for `primary` becomes a **space-separated list** — the generated name for `base` followed by the one for `primary`. The component writes `className={styles.primary}` and the element carries both classes. Two practical consequences: - the CSS for `.base` is emitted **once**, however many classes compose it; - anything attached to `.base` — its `:hover` rule, a media query — reaches `.primary` too, because the element really has the `base` class. The docs describe this as pseudo-class rules being "brought along". ## The three sources | Form | Composes from | Typical use | |---|---|---| | `composes: base;` | a class in the same file | variants of one component | | `composes: base from './Button.module.css';` | a local class in another module | a shared Button base reused by a BookCard action | | `composes: sr-only from global;` | a global (unhashed) class | a utility defined in a global stylesheet | Several names can be listed at once (`composes: base rounded;`), and recent versions of the scope transform also accept several groups separated by commas, mixing sources. ## The rules that limit it 1. **Single local class selector only.** The docs: extending "works only for local-scoped selectors and only if the selector is a single class name". The scope transform throws "composition is only allowed when selector is single :local class name" for `.card .title`, `.title:hover` or `#title` — you cannot compose IDs. 2. **Before other declarations.** The docs require `composes` rules to come before other rules in the block; some implementations accept them anywhere, so treat placement as part of the contract, not as something every tool enforces. 3. **Not inside a nested rule.** With native-style nesting, a `composes` inside a rule nested in another rule fails with "composition is not allowed in nested rule". 4. **The name must exist.** An unknown class fails the build with "referenced class name … not found" — unlike a misspelt key in JavaScript, which is silent. 5. **No cycles.** Circular composition leaves the override order undefined, and the module system may emit an error. ## Who wins when both classes set a property Composition adds classes; it does not rank them. Both rules have one-class specificity, so the **later rule in the emitted CSS** wins: - **Same file.** Source order decides. If `.primary` is written **above** `.base`, any property both rules set resolves in `.base`'s favour — the composing class does not automatically override what it composes. - **Different files.** The order in which two modules' CSS lands in the page depends on imports and chunking. The docs state that when composing multiple classes from different files "the order of appliance is *undefined*" and advise never defining different values for the same property in classes composed together from different files. ## How it compares with other reuse - **Copying declarations** (a mixin, or `@apply`-style inlining in some tools) duplicates CSS into each rule and lets the copy be overridden locally; `composes` duplicates nothing and relies on two classes being present. - **Passing two classes by hand** in JavaScript achieves the same result at the call site; `composes` moves that decision into the stylesheet, so every use of `styles.primary` gets the base automatically. The docs' own guidance: keep each class doing one thing, and keep composition **hierarchical** — a base, then variants — rather than a web of classes composing each other. ## Mistakes that show up in review - **Composing to override.** Writing `composes: base;` and then redefining half of `.base`'s properties works only while `.primary` stays below `.base` in the file; reorder the file and the override flips. - **Cross-file overlap.** A BookCard class that composes the shared Button base and also sets `padding` depends on emitted order between two modules — move the variant into the Button module instead. - **Composing an element-scoped rule.** Wanting `.card .title` to compose something is a sign the class should be split: give the title its own class and compose on that. - **Forgetting the map grows.** Each composed name is another class in the markup; deep chains of composition produce long `class` attributes that are hard to read in DevTools.
- Why can `.card .title { composes: base; }` not compile, while `.title { composes: base; }` can?Composition changes what the map exports for one class name. A compound or descendant selector has no single class to attach the extra names to, so the scope transform rejects anything but a single local class selector, and IDs are refused for the same reason.
- A BookCard's `.reserve` composes `.base` from Button.module.css and also sets `padding`; sometimes the base padding wins. Why?Both classes are on the element with equal specificity, so emitted CSS order decides, and between two module files that order depends on import and chunk order, which the CSS Modules docs call undefined. Move the padding into a variant inside Button.module.css instead.
- `composes` copies the base class's declarations into the composing rule.
- A composing class always overrides the class it composes.
- `composes` works on any selector, including `.card .title` or an ID.
- Composing from two different files applies them in the order listed.
- Global classes cannot be composed into a module class.