In a CSS Modules file, how do `:global` and `:local` work, and how do you style a component when a dialog adds `is-modal-open` to body?
answer
- outside code sets plain names
- local name never matches
- targeted form versus shorthand
- keyframes and animation opt-outs
- pure mode needs one local name
basics
~20 sA class set by code outside the module keeps its plain name, so it must be marked global: :global(.is-modal-open) .catalogue { … } keeps that class unhashed while .catalogue stays local. :local switches back to local scope.
solid answer
~40 sIn local mode every class, ID and keyframes name not wrapped in `:global` is rewritten, so `.is-modal-open .catalogue` compiles to a generated name the dialog script never sets and matches nothing. `:global(.is-modal-open) .catalogue { overflow: hidden; }` leaves just the parenthesised part plain. There are two forms: the **targeted** `:global(.x)` affects only what is inside the parentheses, while the **shorthand** `:global .x .y` switches the rest of the selector to global until a `:local` switches it back. The same applies to `@keyframes :global(spin)` and `global(name)` in an `animation` value. Global names are not added to the class map, so components apply them as literal strings. Under a **pure** mode, a selector must still contain at least one local class or ID — `:global(.is-modal-open)` alone is rejected.
code
css · 19 lines/* Catalogue.module.css */
.catalogue {
display: grid;
}
/* body.is-modal-open is set by the dialog script */
:global(.is-modal-open) .catalogue {
overflow: hidden;
filter: blur(2px);
}
/* a third-party widget's own class, kept under our root */
.searchBar :global(.autocomplete-item) {
padding-block: 0.25rem;
}
@keyframes :global(spin) {
to { transform: rotate(1turn); }
}go deeper
Recall that a class set outside the module must be written inside :global(...) because local names are rewritten and would never match.
Explain the targeted form against the shorthand, :local switching back, global keyframes, and that global names do not appear in the class map.
Show how you keep escapes contained — global anchor, local target, third-party classes nested under a local root — and how pure mode enforces it.
Decide whether a codebase runs modules in pure mode, and how many audited exemptions it tolerates, as the price of keeping page-wide rules out of component files.
## Why an outside class needs an escape hatch A CSS Module is **local by default**: the transform rewrites every class name, ID and keyframes name in the file to a generated name unless told otherwise, and components get those names from the class map. That works for classes the component applies itself. It fails for a class that something **outside** the module sets: - a dialog script toggling `is-modal-open` on `body`; - a third-party autocomplete rendering `.autocomplete-item` inside the SearchBar; - HTML from a CMS, a server template or another team's global stylesheet. Those elements carry the **plain** name. A local `.is-modal-open` in the module compiles to something like `.Catalogue_is-modal-open__z8`, which nothing ever sets, so the rule silently never matches. ## The forms | Written in the module | Compiles to | Meaning | |---|---|---| | `:global(.is-modal-open) .catalogue` | `.is-modal-open .<local catalogue>` | **targeted**: only the parenthesised part is global | | `.searchBar :global(.autocomplete-item)` | `.<local searchBar> .autocomplete-item` | reach a third-party class inside your own component | | `:global .a .b` | `.a .b` | **shorthand**: everything after it is global | | `.a :global .b :local(.c)` | `.<local a> .b .<local c>` | `:local` switches back | | `@keyframes :global(spin)` | `@keyframes spin` | a keyframes name other files can use | | `animation: global(spin) 1s` | `animation: spin 1s` | reference a global animation from a local rule | The targeted form is safer: the shorthand changes the mode for **the rest of the selector**, so a forgotten `:local` turns every later class global without any warning. When a selector is switched to global mode, global mode also applies to that rule's declarations — an `animation` inside it refers to a global keyframes name unless marked `local(...)`. ## The modes The local-by-default transform has three modes: 1. **local** (the default) — names are local; you opt out with `:global`. 2. **global** — names are left alone; you opt in with `:local`. Useful when a legacy stylesheet is processed by the same pipeline. 3. **pure** — like local, but every selector must contain **at least one local class or ID**. `:global(.is-modal-open) .catalogue` passes; `:global(.is-modal-open) { … }` or a bare `img { … }` is rejected. A `/* cssmodules-pure-ignore */` comment exempts one selector and `/* cssmodules-pure-no-check */` at the top of a file exempts the file. Pure mode is the guard rail that keeps a module from quietly growing page-wide rules; toolchains expose it differently (webpack's css-loader, for example, accepts `pure` as a modules mode). ## What global names do to the class map - A name written inside `:global(...)` is **not** exported by default; `styles.isModalOpen` is `undefined`. - The dialog script or component applies the literal string `is-modal-open`. - Some toolchains can also export global names into the map, but the default is not to. ## Practical rules for the catalogue app - Keep the global class **as the anchor**, the local class **as the target**: `:global(.is-modal-open) .catalogue`. The rule then styles only this component's element, under a page-wide state. - Never write `:global(.catalogue)` to "make it work" — that publishes your component's class to the whole app and reintroduces the clashes CSS Modules removed. - For a third-party widget, nest its class under your local root: `.searchBar :global(.autocomplete-item)`, so the override cannot leak to other instances of the widget elsewhere. - Prefer the targeted form; reserve the shorthand for selectors that are global from the first token. ## Debugging a rule that never matches 1. **Inspect the element** and copy its actual class list. 2. **Find the compiled rule** in the emitted CSS and compare: a hashed version of a class the element carries in plain form means that class needed `:global`. 3. **Check the opposite case**: a plain class in the compiled selector that the element carries only in hashed form means a shorthand `:global` swallowed a class meant to stay local. 4. **Look for the keyframes**: an animation that never runs often references a local keyframes name from another file, which needs a global keyframes name or the animation defined in the same module.
- Why is `:global(.catalogue) { … }` a poor fix when a local rule does not match?It makes the component's own class page-wide, so any other `.catalogue` anywhere now collides with it — the clash CSS Modules exist to prevent. Keep only the externally set class global and leave your own class local.
- In a CSS Modules file, what goes wrong with `.a :global .b .c`?The shorthand switches everything after it to global, so `.c` is left plain as well. If `.c` was meant to be the component's class, it now matches any `.c` in the app. Write `.a :global(.b) .c` or switch back with `:local(.c)`.
- Wrapping the whole selector in `:global` is the normal fix for a non-matching rule.
- `:global(.x)` also adds `x` to the class map.
- The shorthand `:global` affects only the next class.
- A body-level state class can be written as a local class.
- Pure mode forbids `:global` entirely.