{"id":13805754,"url":"https://github.com/webark/ember-component-css","last_synced_at":"2025-05-13T21:31:21.271Z","repository":{"id":28180860,"uuid":"31682410","full_name":"webark/ember-component-css","owner":"webark","description":"An Ember CLI addon which allows you to specify styles for individual components","archived":false,"fork":false,"pushed_at":"2023-03-04T15:14:08.000Z","size":2035,"stargazers_count":537,"open_issues_count":55,"forks_count":115,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-30T17:03:57.159Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webark.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-03-04T22:06:24.000Z","updated_at":"2025-03-13T23:28:38.000Z","dependencies_parsed_at":"2024-01-09T05:01:22.908Z","dependency_job_id":"12f2b509-a451-46e1-813f-082db6e1ec1e","html_url":"https://github.com/webark/ember-component-css","commit_stats":{"total_commits":268,"total_committers":52,"mean_commits":5.153846153846154,"dds":0.6828358208955223,"last_synced_commit":"fee293efff035e5f999bf65a99d8b980a627ac24"},"previous_names":["ebryn/ember-component-css"],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webark%2Fember-component-css","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webark%2Fember-component-css/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webark%2Fember-component-css/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webark%2Fember-component-css/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webark","download_url":"https://codeload.github.com/webark/ember-component-css/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254030970,"owners_count":22002681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:01:04.531Z","updated_at":"2025-05-13T21:31:16.231Z","avatar_url":"https://github.com/webark.png","language":"JavaScript","readme":"# ember-component-css [![Build Status](https://github.com/ebryn/ember-component-css/actions/workflows/ci.yml/badge.svg)](https://github.com/ebryn/ember-component-css/actions/workflows/ci.yml) [![Ember Observer Score](https://emberobserver.com/badges/ember-component-css.svg)](https://emberobserver.com/addons/ember-component-css)\n\nAn Ember CLI addon which allows you to specify component-specific style sheets in an app, addon, engine, or in-repo addon.\n\nContributions are welcome! Feel free to open up a pull request or issue, and join the **#e-component-css** channel on the [official Ember Discord server](https://discord.gg/zT3asNS) if you have further questions, concerns, or ideas. Thanks! :smile:\n\n## Installation\n\n`ember install ember-component-css`\n\n## Usage\n\nRules defined in the style-sheets will automatically be namespaced with an autogenerated class. That autogenerated class will also be injected into your component's `classNames` property. This enables you to worry less about rules clashing across component styles.\n\nFor example, given this `app/my-component/styles.scss` file for 'pods',\n\nor this `app/styles/component-styles/my-component.scss` file for 'classic':\n\n```scss\n\u0026 {  // ampersand refers to the component itself (parent selector)\n  padding: 2px;\n}\n.urgent {\n  color: red;\n\n  span {\n    text-decoration: underline;\n  }\n}\n```\n\nYour generated CSS output will look something like:\n\n```css\n.__my-component__a34fba {\n  padding: 2px;\n}\n.__my-component__a34fba .urgent {\n  color: red;\n}\n.__my-component__a34fba .urgent span {\n  text-decoration: underline;\n}\n```\n\nA typical component invocation that looks like this:\n\n`{{my-component}}`\n\nwill generated markup like:\n\n`\u003cdiv class=\"__my-component__a34fba\"\u003e\u003c/div\u003e`\n\n### Inclusion\n\nTo use this addon you *MUST*, import `pod-styles` into your base stylesheet.\n\n```scss\n// app/styles/app.scss\n@import \"pod-styles\";\n```\n\n```scss\n// app/styles/app.less\n@import \"pod-styles\";\n```\n\n```scss\n// app/styles/app.styl\n@import 'pod-styles'\n```\n\n```css\n/* app/styles/app.css */\n@import \"pod-styles.css\";\n```\n\nAnd that is it! The `pod-styles` file is generated during the build and will then be pulled into your other stylesheet to be processed like normal.\n\nNote: If you are using more than one type of component style files (ie a .less file and a .scss file) then you will need to add the extension to the @import. Otherwise the extension can be left off.\n\n### Usage with pods structure\n\nTo use this with pods, you just need to include a style file in your component pods directory alongside your `template.hbs` or `component.js` files.\n\n### Usage with routes\n\nTo use this with routes you need to use pods for the routes and modify the `application.hbs` template a little bit.\nLet's assume your `application.hbs` template looks like this:\n\n```hbs\n{{outlet}}\n```\n\nTo be able to use this for routes, you need to add a wrapping `div` around the outlet:\n\n```hbs\n\u003cdiv class={{routeStyleNamespaceClassSet}}\u003e\n  {{outlet}}\n\u003c/div\u003e\n```\n\nAfter that it's quite easy: add a style file in your route directory alongside your `route.js` or `template.hbs` files.\n\nAn individual controller also has access to a `styleNamespace` property that is the namespace for a given route. This can be used for various use cases. (like enabling BEM style similar to how the `styleNamespace` is used in a component)\n\n### Usage with classic (non pod) structure\n\nYou can use classic Ember app structure by placing component styles in\n`app/styles/component-styles`. Name your style files after the component name,\nfor example `my-component.scss`. The directory where styles are fetched from can\nbe configured as shown [below](#configuration). It's possible to use a mixture\nof classic and pod structured styles in the same app, if you use both styles for\nthe same component both are included but the pod style will take precedence.\n\n### Use in addons\nIn order to use this inside of an addon, you need to add your style files inside of the components in the\naddon directory. You will then be able to import the 'pod-styles' file inside of your addon style file which\nis in the `/addon/styles` directory. These styles will then be added to the `vendor.css` file like normal.\n\nIf you are using classic (non pod) structure, your addon directory structure might look like:\n```\nyourAddonDirectory\n│   index.js\n│   ... etc\n└───addon\n│   └───components\n│       │   yourAddonComponent.js\n│   └───templates\n│       │   yourAddonComponent.hbs\n│   └───styles\n│       │   addon.scss (includes the 'pod-styles' import)\n│       └───component-styles (this dir name is configurable)\n│           │   yourAddonComponent.scss\n└───app\n    └───components\n        │   yourAddonComponent.js\n```\n\nIf you are extending the `include` method in your addon, please make sure you call the super like this\n```js\n  included: function(app) {\n    this._super.included.apply(this, arguments);\n    ...\n  }\n```\n\nBe sure \"ember-component-css\" is listed under the \"dependencies\" key of your addon's `package.json` file, rather than \"devDependencies\". Don't forget, if you are using `ember-cli-sass` for your addon's styles, it will need to be in \"dependencies\" as well.\n\nFinally, if your addon is compiling the expected CSS into the host's `vendor.css` output, but the expected classes are not being set on your components' HTML elements, you will need to [run your addon _after_ ember-component-css](https://ember-cli.com/extending/#configuring-your-ember-addon-properties):\n```js\n// package.json\n{\n  // ...\n  \"dependencies\": {\n    // ...\n    \"ember-component-css\": \"\u003e= 0.6.4\",\n    // ...\n  },\n  // ...\n  \"ember-addon\": {\n    \"configPath\": \"tests/dummy/config\",\n    \"after\": \"ember-component-css\"\n  }\n}\n```\n\n### Plain css usage\nIn order to use this with plain css files, you need to install [`ember-cli-postcss`](https://github.com/jeffjewiss/ember-cli-postcss) and configure it with [`postcss-import`](https://github.com/postcss/postcss-import).\n\n```\nember install ember-component-css\nember install ember-cli-postcss\nnpm install postcss-import --save-dev\n```\nThen in your `ember-cli-build.js` you can configure it as such.\n```js\nvar EmberAddon = require('ember-cli/lib/broccoli/ember-addon');\nvar CssImport = require('postcss-import');\n\nmodule.exports = function(defaults) {\n  var app = new EmberAddon(defaults, {\n    postcssOptions: {\n      compile: {\n        enabled: true,\n        plugins: [{\n          module: CssImport,\n        }]\n      }\n    }\n  });\n\n  return app.toTree();\n};\n```\n\nYou can also add in [`postcss-cssnext`](https://github.com/MoOx/postcss-cssnext) or any other\npostcss plugins in this way too.\n\n*Things like [`ember-cli-autoprefixer`](https://github.com/kimroen/ember-cli-autoprefixer) will work out of the box and do not need to be added in as a postcss plugin.*\n\n### Getting the generated class name\n\nYou also have access to the generated class name to use in your templates. There is a computed property `styleNamespace` This can be used to pass the class name to things like [`ember-wormhole`](https://github.com/yapplabs/ember-wormhole) or for use in BEM style classnames.\nAn example of BEM usage would be\n\n`my-component/template.hbs`\n```handlebars\n\u003cbutton class=\"{{styleNamespace}}__button\"\u003e\n  Normal button\n\u003c/button\u003e\n\u003cbutton class=\"{{styleNamespace}}__button {{styleNamespace}}__button--state-success\"\u003e\n\tSuccess button\n\u003c/button\u003e\n\u003cbutton class=\"{{styleNamespace}}__button {{styleNamespace}}__button--state-danger\"\u003e\n\tDanger button\n\u003c/button\u003e\n```\n`my-component/styles.scss`\n```scss\n\u0026__button {\n  display: inline-block;\n  border-radius: 3px;\n  padding: 7px 12px;\n  border: 1px solid #D5D5D5;\n  background-image: linear-gradient(#EEE, #DDD);\n  font: 700 13px/18px Helvetica, arial;\n\n  \u0026--state-success {\n    color: #FFF;\n    background: #569E3D linear-gradient(#79D858, #569E3D) repeat-x;\n    border-color: #4A993E;\n  }\n\n  \u0026--state-danger {\n    color: #900;\n  }\n}\n```\n\n*`componentCssClassName` will be officially deprecated, then removed in future versions. Will be migrating to the more appropriately named `styleNamespace`*\n\n#### Using the generated class name in `classNameBindings`\n\nYou can build your own computed properties on top of `styleNamespace`. One use case is using it to build a `classNameBinding`:\n\n`my-component/component.hbs`\n```js\nclassNameBindings: ['customBinding'],\n  stateProperty: false,\n  customBinding: computed('styleNamespace', 'stateProperty', function() {\n    if (this.get('stateProperty')) {\n      return `${this.get('styleNamespace')}--state`;\n    } else {\n      return '';\n    }\n  }),\n```\n`my-component/styles.scss`\n```scss\n\u0026 {\n  background: blue;\n}\n\u0026--state {\n  background: red;\n}\n```\n\n### Special Tag-less components\n\nOn the special cases of tag-less components (this functionality is used putting a `tagName: ''` value in the component), the styles are not attached to the DOM, as this addon needs a tag to attach the generated class name. In those special cases, you can use the `styleNamespace`* classname if you want to attach to a another element in the application (or more coherently inside the tag-less component).\n\n### Configuration\n\nYou can set the following configuration options in your `config/environment.js` file:\n\n```js\nENV['ember-component-css'] = {\n  option: 'value'\n}\n```\n\n**namespacing(_enabled_)**\n\nDefaults to true. Set this option to `false` to disable the namespacing feature of Ember Component CSS.\n\n```js\nENV['ember-component-css'] = {\n  namespacing: false\n}\n```\n\nThis changes the default behavior in two ways:\n\n 1. The autogenerated component class is no longer added to your component's HTML\n 2. Your pod CSS files are no longer namespaced using the autogenerated component class.\n\n**classicStyleDir**\n\nDefaults to `component-styles`. Set this to the directory where your classically\nstructured styles live (within `/app/styles`). For example:\n\n```js\nENV['ember-component-css'] = {\n  classicStyleDir: 'my-styles'\n}\n```\n\n**excludeFromManifest**\n\nDefaults to `[]`. Set this option to one or more matcher expression (regular expression, glob string, or function).\nStyle files matching the expresion(s) will be namespaced but not imported in the `pod-styles` manifest. You will\nneed to import the matching style files manually in your CSS. This can be useful when you need to control the order\nin which specific style files need to be imported.\n\nExample:\nYou want to have a separate style file for each media-query breakpoint. You want to be sure that `_style-1366.scss`\nwill be imported before `_style-960.scss`\n\n```\n.\n└── my-component/\n    ├── _style-1366.scss\n    ├── _style-960.scss\n    ├── main.scss\n    ├── component.js\n    └── template.hbs\n```\n\n```sass\n// main.scss\n@import \"./_style-1366\"\n@import \"./_style-960\"\n```\n\n```js\nENV['ember-component-css'] = {\n  excludeFromManifest: ['**/_style-*']\n}\n```\n\n**patchClassicComponent**\n\nSet this option to `false` to prevent automatic `Component.reopen()` call which injects\nthe autogenerated class into component's `classNames` property.\n\nYou would need to use {{this.styleNamespace}} in *all* of your templates instead:\n\n```hbs\n\u003cdiv class=\"wrapper {{this.styleNamespace}}\"\u003e\n  Content goes here.\n\u003c/div\u003e\n```\n\nThis is required to use `ember-component-css` with Ember 4+ since `Component.reopen()` was removed from Ember.js codebase.\nFor more details you may refer to [deprecation page](https://deprecations.emberjs.com/v3.x#toc_ember-component-reopen).\n\n\n### [The announcement from EmberConf 2015](https://youtu.be/T1zxaEKeq3E)\n[![CSS is hard - EmberConf 2015](http://f.cl.ly/items/1a3a3r1C1y0D060D3j3u/EmberConf%202015%20-%20CSS%20Is%20Hard%20-%20YouTube%202015-03-22%2018-33-41.jpg)](https://youtu.be/T1zxaEKeq3E)\n","funding_links":[],"categories":["Packages"],"sub_categories":["CSS \u0026 etc"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebark%2Fember-component-css","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebark%2Fember-component-css","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebark%2Fember-component-css/lists"}