ember-scoped-css

Scope your component styles and never worry about a collision ever again.

const greeting = "hello world";

<template>
  <div>{{greeting}}</div>

  <style scoped>
    div {
      color: blue;
    }
  </style>
</template>

becomes the equivelent of;

const greeting = "hello world";

<template>
  <div class="abcd1234">{{greeting}}</div>

  <style scoped>
    div.abcd1234 {
      color: blue;
    }
  </style>
</template>

This is a build-time-only addon, so there is no need to worry about runtime performance.

You can also write your styles as a co-located .css file, right next to your .gjs/.gts files. Every selector you write in your styles is automatically scoped to the component. So you can develop your component with styles isolated from the rest of the application and you don't have to worry about CSS selectors collisions or issues with the CSS cascade.

See Usage for details.

If you want to read more specifics on how this addon achieves isolation with CSS you can read more in the detailed CSS isolation documentation

As selectors are scoped/renamed during the build process. So there is no performance hit when running the app.

The philosophy of ember-scoped-css is to stick as close to CSS and HTML as possible and not introduce new syntax or concepts unless it is absolutely necessary.

You may also find the docs on CSS @layer interesting. This build tool can emit CSS in a @layer.

Compatibility

• Vite
• V2 addons with @embroider/addon-dev @ v8+ (or similar)
• For hbs, broccoli, or webpack-based builds, view this version of the docs
  • For bugfixes for the pre-ember-scoped-css-1.0 code, PR here

You Have	ember-scoped-css	ember-scoped-css-compat	docs
vite	>= 1.0.0	🚫	main
gjs / gts library (no hbs)	>= 1.0.0	🚫	main
webpack	<= 0.24.3	<= 10.0.0	0.24.3
hbs	<= 0.24.3	<= 10.0.0	0.24.3
ember-template-imports@v4 or babel-plugin-ember-template-compilation@2.2.5+	0.19.0	10.0.0	0.19 - 0.24
ember-template-imports@v3 or babel-plugin-ember-template-compilation@2.2.1 or rollup-plugin-glimmer-template-tag	<= 0.18.0	<= 9.0.0	0.18
classic components	<= 0.18.0	<= 8.0.0	0.18
ember < 4	<= 0.18.0	<= 8.0.0	0.18

Installation for a Vite app

npm install --save-dev ember-scoped-css

Configuration

In your vite.config.js, import and add the scopedCSS plugin:

import { defineConfig } from 'vite';
import { scopedCSS } from 'ember-scoped-css/vite';

export default defineConfig({
  // ...
  plugins: [
    scopedCSS(),
    // ...
  ],
});

and then in your babel.config.mjs, add a template-transform:

import * as scopedCSS from "ember-scoped-css/build";

module.exports = {
  plugins: [
    // ...
    [scopedCSS.babelPlugin, {}],
    [
      'babel-plugin-ember-template-compilation',
      {
        // ...
        transforms: [scopedCSS.templatePlugin({})],
      },
    ],
    // ...
  ],
  // ...
};

If you have a rollup config:

import * as scopedCss from 'ember-scoped-css/build';

// ...
plugins: [
    scopedCss.rollupPlugin(),
]

Installation for an embroider app

npm install --save-dev ember-scoped-css ember-scoped-css-compat

Configuration

All forms of scopedCss take an options hash except for the rollup and vite plugins.

Configuration in the two locations in the babel config should match, for example:

plugins: [
  [scopedCSS.babelPlugin, { layerName: 'my-library' }],

  [
    'babel-plugin-ember-template-compilation',
    {
      targetFormat: 'hbs',
      transforms: [scopedCSS.templatePlugin({ layerName: 'my-libarry' })],
    },
  ],
],

Usage

With ember-scoped-css you define styles in an inline <style scoped> block or .css files that are colocated with your components

// ...

<template>
  <div data-test-my-component class='hello-class header'>
    <b>Hello</b>, world!
  </div>

  <style scoped>
    .hello-class {
      color: red;
    }

    /* the :global() pseudo-class is used to define a global class. 
       It mean that header class wont be scoped to that component */
    .hello-class:global(.header) {
      font-size: 20px;
    }

    b {
      color: blue;
    }
  </style>
</template>

Note that <style> (without scoped) will continue to work as it does today and be "global styles"

inline / conditional CSS

Like the example above, we can specify the scoped attribute on the <style> tag, but if we add the inline attribute as well, the <style> tag will not be extracted to a CSS file during your app's build -- it will be left inline.

This can be useful for conditionally applied styles.

[!IMPORTANT] While using inline enables conditional styles, if multiple of the same component are rendered on a page, the CSS from both <style scoped inline> elements will be applied to both renderings of that component.

// ...

<template>
  <div data-test-my-component class='hello-class header'>
    <b>Hello</b>, world!
  </div>

  <style scoped inline>
    .hello-class {
      color: red;
    }

    /* the :global() pseudo-class is used to define a global class. 
       It mean that header class wont be scoped to that component */
    .hello-class:global(.header) {
      font-size: 20px;
    }

    b {
      color: blue;
    }
  </style>
</template>

separate CSS file

<div data-test-my-component class='hello-class header'><b>Hello</b>, world!</div>

/* src/components/my-component.css */
.hello-class {
  color: red;
}

/* the :global() pseudo-class is used to define a global class. It mean that header class wont be scoped to that component */
:global(.header) {
  font-size: 20px;
}

b {
  color: blue;
}

NOTE: that if you're using pods, css co-located with templates/routes/etc will need to be named styles.css

Difference with @scope

The @scope at-rule will scope all CSS defined within a <style> tag to the parent element.

<div>
  <style>
    @scope {
      p { color: red; }
    }
  </style>

  <p>this is red</p>
</div>

<p>not red</p>

In this example, it is effectively the same as:

<!-- style scoped must be at the root of the template-area -->
<style scoped>
    p.inner { color: red; }
</style>

<div>
  <p class="inner">this is red</p>
</div>

<p>not red</p>

But the nice thing is that you don't need to use classes with @scope.

A potential downside to @scope is that it operates deeply -- where as <style scoped> will only apply its styles to the immediate component -- meaning that nested elements / components don't accidentally get surprise styles.

For example:

const Inner = <template>
  <p>
    inner (also red)
  </p>
</template>;

const Outer = <template>
  <div>
    <style>
      @scope {
        p { color: red; }
      }
    </style>

    <p>this is red</p>

    <Inner />
  </div>
</template>

Where as with <style scoped>

const Inner = <template>
  <p>
    inner (not red)
  </p>
</template>;

const Outer = <template>
  <style scoped>
    p { color: red; }
  </style>

  <div>
    <p>this is red</p>

    <Inner />
  </div>
</template>

Passing classes as arguments to a component

There is a scopedClass helper that you can use to pass a class name as an argument to a component. The helper takes a class name and returns a scoped class name. scopedClass helper is replaced at build time so there is no performance hit when running the app.

import { scopedClass } from 'ember-scoped-css';

<template>
  <OtherComponent @internalClass={{scopedClass 'hello-class'}} />
  <OtherComponent @internalClass={{(scopedClass 'hello-class')}} />
  <OtherComponent
    @internalClass={{concat (scopedClass 'hello-class') ' other-class'}}
  />
</template>

Testing

As classes are renamed during the build process you can't directly verify if classes are present in your tests. To solve this problem you can use the scopedClass function from the ember-scoped-css/test-support module. The function takes the class names and path to the CSS file where are the classes defined and returns the scoped class names.

The path to the CSS file is always relative to the V2 addon root no matter where the test is located.

import { scopedClass } from 'ember-scoped-css/test-support';

test('MyComponent has hello-class', async function (assert) {
  assert.expect(1);

  await render(<template>
    <MyComponent />
  </template>);

  const rewrittenClass = scopedClass(
    'hello-class',
    '<module-name>/components/my-component'
  );

  assert.dom('[data-test-my-component]').hasClass(rewrittenClass);
});

Linting

ember-scoped-css exports a ember-template-lint plugin with one rule scoped-class-helper. This lint rule is intended to help you prevent improper use of the scopedClass helper which might not be immediately obvious during regular development. You can read more information in the lint rules documentation

Steps for adding the rule to the project

1. Add ember-scoped-css plugin to .template-lintrc.js

'use strict';

module.exports = {
	plugins: [
+    'ember-scoped-css/src/template-lint/plugin'
  ],

2. Add scoped-class-helper rule to .template-lintrc.js

'use strict';

module.exports = {
	plugins: [
    'ember-scoped-css/src/template-lint/plugin'
  ],
  rules: {
+    'scoped-class-helper': 'error',
+    'no-forbidden-elements': ['meta', 'html', 'script'], // style removed
  }

License

This project is licensed under the MIT License.