Ember-css-modules-active-route NPM

ember-css-modules-active-route

:app-root and :document-root selectors to apply styles to the root element, when a route is active.

Installation

ember install ember-css-modules-active-route ember-css-modules

This is a plugin for ember-css-modules, so you need to have it installed as well.

Usage

:app-root: Maps to the root element of your application. Usually <body>.
:document-root: Maps to the documentElement / :root, which is the <html> element.

Example

Router.map(function() {
  this.route('foo', function() {
    this.route('bar');
  });
  this.route('qux');
});

/* app/foo/styles.css */

:app-root {
  background: green;
}

/* app/foo/index/styles.css */

:app-root {
  background: red;
}

When the user enters the foo route, the :app-root pseudo-selector will be applied to the app's rootElement (<body>). The background of the page will be red, as foo.index overrides foo.

When the user navigates to foo.bar, the background will turn green, as the user has left the foo.index route and the override no longer takes effect.

When the user navigates to qux, the background will become transparent again, as no route styles are active any more.

Combining Selectors

You can also combine the :app-root & :document-root selectors with other regular selectors. For instance, instead of just using :document-root, which targets the :root element (<html>), you can target child elements instead:

:document-root :global(.some-cookie-banner) {
  display: none;
}

In this example, <div class="some-cookie-banner"> is inserted by the backend and would be hidden, while the user is on a certain route.

Specificity

CSS Specificity can be a tricky thing. This addon tries to make everything work out of the box. For every level of nesting, the selector specificity will be increased automatically. This way, overrides in child routes actually override declarations in parent routes, without the source order being relevant.

You can also manually set the specificity, like so:

:app-root(3) {
  background: red;
}

:app-root(2) {
  background: green;
}

The background will be red, as 3 is a higher specificity than 2.

How does it work?

The :app-root / :app-root(n) and :document-root / :document-root(n) selectors are replaced with "magic" class name selectors by lib/route-plugin.js. These selectors are repeated n times to raise them to the necessary specificity level.

n can either be specified explicitly as :app-root(n), or when used as :app-root will be derived from the depth of route nesting by counting the / in the file path of the respective styles.css. This ensures that rules in nested child routes override rules from their parent routes.

:app-root {
  background: yellow;
}
:app-root(3) {
  background: green;
}
:app-document(1) body {
  background: blue;
}

/* becomes */

/* Class name may be repeated more often depending on level of nesting. */
.css-modules-active-route-app.css-modules-active-route-app {
  background: yellow;
}

/* With an explicit `n` provided, the class name is repeated that many times. */
.css-modules-active-route-app.css-modules-active-route-app.css-modules-active-route-app {
  background: green;
}

/* Combining with other selectors is possible. */
.css-modules-active-route-document body {
  background: blue;
}

When the a transition is started or finished the CSSModulesActiveRouteService resolves the styles for the current route hierarchy via the Ember container using the route name. This implies, that you cannot render custom / non-default templates for routes, which is deprecated anyway.