diff --git a/aio/content/guide/component-styles.en.md b/aio/content/guide/component-styles.en.md new file mode 100644 index 00000000000000..03677ce0ce8c85 --- /dev/null +++ b/aio/content/guide/component-styles.en.md @@ -0,0 +1,355 @@ +# Component styles + +Angular applications are styled with standard CSS. That means you can apply +everything you know about CSS stylesheets, selectors, rules, and media queries +directly to Angular applications. + +Additionally, Angular can bundle *component styles* +with components, enabling a more modular design than regular stylesheets. + +This page describes how to load and apply these component styles. + +You can run the in Stackblitz and download the code from there. + +## Using component styles + +For every Angular component you write, you may define not only an HTML template, +but also the CSS styles that go with that template, +specifying any selectors, rules, and media queries that you need. + +One way to do this is to set the `styles` property in the component metadata. +The `styles` property takes an array of strings that contain CSS code. +Usually you give it one string, as in the following example: + + + +## Style scope + +
+ +The styles specified in `@Component` metadata _apply only within the template of that component_. + +
+ +They are _not inherited_ by any components nested within the template nor by any content projected into the component. + +In this example, the `h1` style applies only to the `HeroAppComponent`, +not to the nested `HeroMainComponent` nor to `

` tags anywhere else in the application. + +This scoping restriction is a ***styling modularity feature***. + +* You can use the CSS class names and selectors that make the most sense in the context of each component. + + +* Class names and selectors are local to the component and don't collide with + classes and selectors used elsewhere in the application. + + +* Changes to styles elsewhere in the application don't affect the component's styles. + + +* You can co-locate the CSS code of each component with the TypeScript and HTML code of the component, + which leads to a neat and tidy project structure. + + +* You can change or remove component CSS code without searching through the + whole application to find where else the code is used. + +{@a special-selectors} + +## Special selectors + +Component styles have a few special *selectors* from the world of shadow DOM style scoping +(described in the [CSS Scoping Module Level 1](https://www.w3.org/TR/css-scoping-1) page on the +[W3C](https://www.w3.org) site). +The following sections describe these selectors. + +### :host + +Use the `:host` pseudo-class selector to target styles in the element that *hosts* the component (as opposed to +targeting elements *inside* the component's template). + + + + +The `:host` selector is the only way to target the host element. You can't reach +the host element from inside the component with other selectors because it's not part of the +component's own template. The host element is in a parent component's template. + +Use the *function form* to apply host styles conditionally by +including another selector inside parentheses after `:host`. + +The next example targets the host element again, but only when it also has the `active` CSS class. + + + +### :host-context + +Sometimes it's useful to apply styles based on some condition *outside* of a component's view. +For example, a CSS theme class could be applied to the document `` element, and +you want to change how your component looks based on that. + +Use the `:host-context()` pseudo-class selector, which works just like the function +form of `:host()`. The `:host-context()` selector looks for a CSS class in any ancestor of the component host element, +up to the document root. The `:host-context()` selector is useful when combined with another selector. + +The following example applies a `background-color` style to all `

` elements *inside* the component, only +if some ancestor element has the CSS class `theme-light`. + + + +### (deprecated) `/deep/`, `>>>`, and `::ng-deep` + +Component styles normally apply only to the HTML in the component's own template. + +Applying the `::ng-deep` pseudo-class to any CSS rule completely disables view-encapsulation for +that rule. Any style with `::ng-deep` applied becomes a global style. In order to scope the specified style +to the current component and all its descendants, be sure to include the `:host` selector before +`::ng-deep`. If the `::ng-deep` combinator is used without the `:host` pseudo-class selector, the style +can bleed into other components. + +The following example targets all `

` elements, from the host element down +through this component to all of its child elements in the DOM. + + + +The `/deep/` combinator also has the aliases `>>>`, and `::ng-deep`. + +
+ +Use `/deep/`, `>>>` and `::ng-deep` only with *emulated* view encapsulation. +Emulated is the default and most commonly used view encapsulation. For more information, see the +[Controlling view encapsulation](guide/component-styles#view-encapsulation) section. + +
+ +
+ +The shadow-piercing descendant combinator is deprecated and [support is being removed from major browsers](https://www.chromestatus.com/features/6750456638341120) and tools. +As such we plan to drop support in Angular (for all 3 of `/deep/`, `>>>` and `::ng-deep`). +Until then `::ng-deep` should be preferred for a broader compatibility with the tools. + +
+ +{@a loading-styles} + +## Loading component styles + +There are several ways to add styles to a component: + +* By setting `styles` or `styleUrls` metadata. +* Inline in the template HTML. +* With CSS imports. + +The scoping rules outlined earlier apply to each of these loading patterns. + +### Styles in component metadata + +You can add a `styles` array property to the `@Component` decorator. + +Each string in the array defines some CSS for this component. + + + + +
+ +Reminder: these styles apply _only to this component_. +They are _not inherited_ by any components nested within the template nor by any content projected into the component. + +
+ +The Angular CLI command [`ng generate component`](cli/generate) defines an empty `styles` array when you create the component with the `--inline-style` flag. + + +ng generate component hero-app --inline-style + + +### Style files in component metadata + +You can load styles from external CSS files by adding a `styleUrls` property +to a component's `@Component` decorator: + + + + + + +
+ +Reminder: the styles in the style file apply _only to this component_. +They are _not inherited_ by any components nested within the template nor by any content projected into the component. + +
+ +
+ + You can specify more than one styles file or even a combination of `styles` and `styleUrls`. + +
+ +When you use the Angular CLI command [`ng generate component`](cli/generate) without the `--inline-style` flag, it creates an empty styles file for you and references that file in the component's generated `styleUrls`. + + +ng generate component hero-app + + +### Template inline styles + +You can embed CSS styles directly into the HTML template by putting them +inside `