composition.md

Composition

You can compose selectors together with composes:

.className {
  color: green;
  background: red;
}

.otherClassName {
  composes: className;
  color: yellow;
}

There can be multiple composes rules, but composes rules must be before other rules. Extending works only for local-scoped selectors and only if the selector is a single class name. When a class name composes another class name, the CSS Module exports both class names for the local class. This can add up to multiple class names.

It's also possible to compose multiple classes with composes: classNameA classNameB;.

Pseudo classes

Classes which have pseudo selectors attached will be brought along when used in a composes statement.

In the example below, otherClassName will also be given the :hover pseudo class defined on className.

.className {
  color: green;
}

.className:hover {
  color: red;
}

.otherClassName {
  composes: className;
  background: black;
}

otherClassName above is the same as defining:

.otherClassName {
  color: green;
  background: black;
}

.otherClassName:hover {
  color: red;
}

Dependencies

Composing from other files

It's possible to compose class names from other CSS Modules.

.otherClassName {
  composes: className from './style.css';
}

When composing multiple classes from different files, the order of appliance is undefined. Do not define different values for the same property in multiple class names from different files when they are composed in a single class.

Composing should not form a circular dependency. Otherwise, it's undefined whether properties of a rule override properties of a composed rule. The module system may emit an error.

We recommend that classes do a single thing and dependencies are hierarchic.

Composing from global class names

It's possible to compose from global class names.

.otherClassName {
  composes: globalClassName from global;
}

Exceptions

:global switches to global scope for the current selector respective identifier. :global(.xxx) respective @keyframes :global(xxx) declares the stuff in parenthesis in the global scope.

Similarly, :local and :local(...) for local scope.

:global(.some-selector) {
  /* ... */
}

If the selector is switched into global mode, global mode is also activated for the rules. (This allows us to make animation: abc; local.)

Example: ``

.localA :global .global-b .global-c :local(.localD.localE) .global-d {
  /* ... */
}