You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Slighlty improve the `viewEncapsulation` documentation (both in code
comments and content files) to make it more clear and understandable.
See angular#44099 (comment)
PR Closeangular#44151
In Angular, component CSS styles are encapsulated into the component's view and don't
4
-
affect the rest of the application.
3
+
In Angular, a component's styles can be encapsulated within the component's host element so that they don't affect the rest of the application.
4
+
5
+
The `Component`'s decorator provides the [`encapsulation`](api/core/Component#encapsulation) option which can be used to control how the encapsulation is applied on a _per component_ basis.
5
6
6
-
To control how this encapsulation happens on a _per
7
-
component_ basis, set the _view encapsulation mode_ in the component metadata.
8
7
Choose from the following modes:
9
8
10
-
-`ShadowDom` view encapsulation uses the browser's built-in shadow DOM implementation (see
to attach a shadow DOM to the component's host element, and then puts the component
13
-
view inside that shadow DOM. The component's styles are included within the shadow DOM.
9
+
-`ViewEncapsulation.ShadowDom`, Angular uses the browser's built-in [Shadow DOM API](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM)) to enclose the component's view inside a ShadowRoot (used as the component's host element) and apply the provided styles in an isolated manner.
10
+
11
+
-`ViewEncapsulation.Emulated`, Angular modifies the component's CSS selectors so that they are only applied to the component's view and do not affect other elements in the application (_emulating_ Shadow DOM behavior). For more details, see [Inspecting generated CSS](guide/view-encapsulation#inspect-generated-css).
14
12
15
-
-`Emulated` view encapsulation (the default) emulates the behavior of shadow DOM by preprocessing
16
-
(and renaming) the CSS code to effectively scope the CSS to the component's view.
17
-
For details, see [Inspecting generated CSS](guide/view-encapsulation#inspect-generated-css).
13
+
-`ViewEncapsulation.None`, Angular does not apply any sort of view encapsulation meaning that any styles specified
14
+
for the component are actually globally applied and can affect any HTML element present within the application.
15
+
This mode is essentially the same as including the styles into the HTML itself.
18
16
19
-
-`None` means that Angular does no view encapsulation.
20
-
Angular adds the CSS to the global styles.
21
-
The scoping rules, isolations, and protections discussed earlier don't apply.
22
-
This mode is essentially the same as pasting the component's styles into the HTML.
17
+
<divclass="alert is-important">
23
18
24
-
To set the component's encapsulation mode, use the `encapsulation` property in the component metadata:
19
+
`ViewEncapsulation.ShadowDom` only works on browsers that have built-in support
20
+
for the shadow DOM (see [Can I use - Shadow DOM v1](https://caniuse.com/shadowdomv1)).
21
+
Not all browsers support it, which is why the `ViewEncapsulation.Emulated` is the recommended and default mode.
`ShadowDom` view encapsulation only works on browsers that have built-in support
29
-
for shadow DOM (see [Can I use - Shadow DOM v1](https://caniuse.com/shadowdomv1)).
30
-
The support is still limited, which is why `Emulated` view encapsulation is the default mode and recommended in most cases.
31
25
32
26
{@a inspect-generated-css}
33
27
34
28
## Inspecting generated CSS
35
29
36
-
When using emulated view encapsulation, Angular preprocesses
37
-
all component styles so that they approximate the standard shadow CSS scoping rules.
30
+
When using the emulated view encapsulation, Angular pre-processes all the component's styles so that they are only applied to the component's view.
38
31
39
-
In the DOM of a running Angular application with emulated view
40
-
encapsulation enabled, each DOM element has some extra attributes
41
-
attached to it:
32
+
In the DOM of a running Angular application, elements belonging to components using emulated view encapsulation have some extra attributes attached to them:
42
33
43
-
<code-exampleformat="">
34
+
<code-exampleformat="html"language="html">
44
35
<hero-details _nghost-pmm-5>
45
36
<h2 _ngcontent-pmm-5>Mister Fantastic</h2>
46
37
<hero-team _ngcontent-pmm-5 _nghost-pmm-6>
@@ -49,18 +40,16 @@ attached to it:
49
40
</hero-detail>
50
41
</code-example>
51
42
52
-
There are two kinds of generated attributes:
43
+
There are two kinds of such attributes:
44
+
45
+
-`_nghost` attributes are added to elements that enclose a component's view and that would be ShadowRoots in a native Shadow DOM encapsulation. This is typically the case for components' host elements.
46
+
-`_ngcontent` attributes are added to child element within a component's view, those are used to match the elements with their respective emulated ShadowRoots (host elements with a matching `_nghost` attribute).
53
47
54
-
- An element that would be a shadow DOM host in native encapsulation has a
55
-
generated `_nghost` attribute. This is typically the case for component host elements.
56
-
- An element within a component's view has a `_ngcontent` attribute
57
-
that identifies to which host's emulated shadow DOM this element belongs.
48
+
The exact values of these attributes are a private implementation detail of Angular. They are automatically generated and you should never refer to them in application code.
58
49
59
-
The exact values of these attributes aren't important. They are automatically
60
-
generated and you should never refer to them in application code. But they are targeted
61
-
by the generated component styles, which are in the `<head>` section of the DOM:
50
+
They are targeted by the generated component styles, which are injected in the `<head>` section of the DOM:
62
51
63
-
<code-exampleformat="">
52
+
<code-exampleformat="css"language="css">
64
53
[_nghost-pmm-5] {
65
54
display: block;
66
55
border: 1px solid black;
@@ -72,25 +61,29 @@ h3[_ngcontent-pmm-6] {
72
61
}
73
62
</code-example>
74
63
75
-
These styles are post-processed so that each selector is augmented
76
-
with `_nghost` or `_ngcontent` attribute selectors.
77
-
These extra selectors enable the scoping rules described in this page.
64
+
These styles are post-processed so that each CSS selector is augmented with the appropriate `_nghost` or `_ngcontent` attribute. These modified selectors make sure the styles to be applied to components' views in an isolated and targeted fashion.
78
65
79
66
## Mixing encapsulation modes
80
67
81
-
Avoid mixing components that use different view encapsulation. Where it is necessary, you should be aware of how the component styles will interact.
68
+
As previously mentioned you specify the encapsulation mode in the Component's decorator on a _per component_ basis, this means that within your application you can have different components using different encapsulation strategies.
69
+
70
+
Although possible, this is not recommended. If it is really needed you should be aware of how the styles of components using different encapsulation modes will interact with each other:
71
+
72
+
- The styles of components with `ViewEncapsulation.Emulated` are added to the `<head>` of the document, making them available throughout the application, but their selectors only affect elements within their respective components' templates.
73
+
74
+
- The styles of components with `ViewEncapsulation.None` are added to the `<head>` of the document, making them available throughout the application, so are completely global and affect any matching elements within the document.
82
75
83
-
- The styles of components with `ViewEncapsulation.Emulated` are added to the `<head>` of the document, making them available throughout the application, but are "scoped" so they only affect elements within the component's template.
76
+
- The styles of components with `ViewEncapsulation.ShadowDom` are only added to the shadow DOM host, ensuring that they only affect elements within their respective components' views.
84
77
85
-
- The styles of components with `ViewEncapsulation.None` are added to the `<head>` of the document, making them available throughout the application, and are not "scoped" so they can affect any element in the application.
78
+
<divclass="alert is-helpful">
86
79
87
-
- The styles of components with`ViewEncapsulation.ShadowDom`are only added to the shadow DOM host, ensuring that they only affect elements within the component's template.
80
+
Styles of `ViewEncapsulation.Emulated` and`ViewEncapsulation.None` components are also added to the shadow DOM host of each `ViewEncapsulation.ShadowDom`component.
88
81
89
-
**All the styles for `ViewEncapsulation.Emulated` and`ViewEncapsulation.None`components are also added to the shadow DOM host of each `ViewEncapsulation.ShadowDom` component.**
82
+
This means that styles for components with`ViewEncapsulation.None`will affect matching elements within shadow DOMs.
90
83
91
-
The result is that styling for components with `ViewEncapsulation.None`will affect matching elements within the shadow DOM.
84
+
This approach may seem counter-intuitive at first, but without it a component with `ViewEncapsulation.None`would be rendered differently within a component using `ViewEncapsulation.ShadowDom`, since its styles would not be available.
92
85
93
-
This approach may seem counter-intuitive at first, but without it a component with `ViewEncapsulation.None` could not be used within a component with `ViewEncapsulation.ShadowDom`, since its styles would not be available.
86
+
</div>
94
87
95
88
### Examples
96
89
@@ -106,7 +99,7 @@ The first example shows a component that has `ViewEncapsulation.None`. This comp
106
99
107
100
Angular adds the styles for this component as global styles to the `<head>` of the document.
108
101
109
-
**Angular also adds the styles to all shadow DOM hosts.** Therefore, the styles are available throughout the application.
102
+
As already mentioned Angular also adds the styles to all shadow DOM hosts. Therefore, the styles are available throughout the whole application.
110
103
111
104
<imgsrc="generated/images/guide/view-encapsulation/no-encapsulation.png"alt="component with no encapsulation">
112
105
@@ -116,14 +109,12 @@ The second example shows a component that has `ViewEncapsulation.Emulated`. This
Similar to `ViewEncapsulation.None`, Angular adds the styles for this component to the `<head>` of the document, and to all the shadow DOM hosts.
120
-
But in this case, the styles are "scoped" by the attributes described in ["Inspecting generated CSS"](#inspecting-generated-css).
112
+
Similar to `ViewEncapsulation.None`, Angular adds the styles for this component to the `<head>` of the document, but with "scoped" styles.
121
113
122
114
Therefore, only the elements directly within this component's template will match its styles.
123
115
Since the "scoped" styles from the `EmulatedEncapsulationComponent` are very specific, they override the global styles from the `NoEncapsulationComponent`.
124
116
125
-
In this example, the `EmulatedEncapsulationComponent` contains a `NoEncapsulationComponent`.
126
-
The `NoEncapsulationComponent` is styled as expected because the scoped styles do not match elements in its template.
117
+
In this example, the `EmulatedEncapsulationComponent` contains a `NoEncapsulationComponent`, but `NoEncapsulationComponent` is still styled as expected since the `EmulatedEncapsulationComponent`'s "scoped" styles do not match elements in its template.
127
118
128
119
<imgsrc="generated/images/guide/view-encapsulation/emulated-encapsulation.png"alt="component with no encapsulation">
129
120
@@ -144,8 +135,8 @@ The styles added by the `ShadowDomEncapsulationComponent` component are availabl
144
135
The `EmulatedEncapsulationComponent` has specific "scoped" styles, so the styling of this component's template is unaffected.
145
136
146
137
But since styles from `ShadowDomEncapsulationComponent` are added to the shadow host after the global styles, the `h2` style overrides the style from the `NoEncapsulationComponent`.
147
-
The result is that the `<h2>` element in the `NoEncapsulationComponent` is colored blue rather than red, which may not be what the component author intended.
138
+
The result is that the `<h2>` element in the `NoEncapsulationComponent` is colored blue rather than red, which may not be what the component's author intended.
148
139
149
140
<imgsrc="generated/images/guide/view-encapsulation/shadow-dom-encapsulation.png"alt="component with no encapsulation">
0 commit comments