[Documentation] Explain how ::ng-deep works #65718
Conversation
Gouvernathor
force-pushed
the
patch-1
branch
from
d0255da to
07cee82
Compare
angular-robot
bot
added
area: docs
JeanMeche
added
cla: no
compiler: template pipeline
and removed
compiler: template pipeline
cla: no
labels
|
Deployed adev-preview for 8acb318 to: https://ng-dev-previews-fw--pr-angular-angular-65718-adev-prev-14gyzu2s.web.app Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt. |
|
I'll wonder about how to make it lint-compliant if the wording and general idea is accepted. The change in the "discouragement" line that I mentioned above, will go in a separate PR, unless someone wants me to add it here and now. |
| *after* `::ng-deep` will be matched with elements irrespective of whether they are inside the component's template. | ||
| For instance: | ||
| - a CSS rule whose selector is `p a` will match `<a>` elements inside the component's template, which are also | ||
| descendants of a `<p>` element that's itself also inside the component's template. That's Angular's default behavior. |
There was a problem hiding this comment.
| descendants of a `<p>` element that's itself also inside the component's template. That's Angular's default behavior. | |
| When using the emulated encapsulation, a selector like `p a`, Angular matches `<a>` elements within the component’s own template that are descendants of a `<p>` element. |
There was a problem hiding this comment.
I disagree with that one. qi think it's important to mention that (1) it's the default behavior in Angular, the baseline against which the rest compares, and (2) that the <p> also needs to be in the template.
There was a problem hiding this comment.
The docs already mentions that emulated encapsulation is the default. I agree about 2., it can be improved.
| For instance: | ||
| - a CSS rule whose selector is `p a` will match `<a>` elements inside the component's template, which are also | ||
| descendants of a `<p>` element that's itself also inside the component's template. That's Angular's default behavior. | ||
| - `::ng-deep p a` will match `<a>` elements anywhere in the page, descendants of a `<p>` element anywhere in the page. |
There was a problem hiding this comment.
A selector like ::ng-deep p a matches anchor elements anywhere in the application, as long as they are descended from a paragraph element anywhere in the application. In effect, this behaves like a global style.
| descendants of a `<p>` element that's itself also inside the component's template. That's Angular's default behavior. | ||
| - `::ng-deep p a` will match `<a>` elements anywhere in the page, descendants of a `<p>` element anywhere in the page. | ||
| That effectively makes it a global style. | ||
| - `p ::ng-deep a` will match `<a>` elements anywhere in the page, but only those that are descendents |
There was a problem hiding this comment.
| - `p ::ng-deep a` will match `<a>` elements anywhere in the page, but only those that are descendents | |
| - In `p ::ng-deep a`, Angular requires the paragraph element to come from the component’s own template, but the anchor element can be anywhere in the application. This means the anchor element may be in the component’s template or in any of its projected or child content. |
| - `p ::ng-deep a` will match `<a>` elements anywhere in the page, but only those that are descendents | ||
| of a `<p>` element inside the component's template. | ||
| So, effectively, the `<a>` can only be in the component's template, or among the component's children. | ||
| - `:host ::ng-deep p a` will match `<a>` elements descendants of `<p>` elements, both being descendants of the component. |
There was a problem hiding this comment.
| - `:host ::ng-deep p a` will match `<a>` elements descendants of `<p>` elements, both being descendants of the component. | |
| - With `:host ::ng-deep p a`, both the paragraph element and the anchor element must be descendants of the component’s host element. They can appear in the component’s template or in the views of its child components, but not elsewhere in the app. |
|
The content is correct but mostly needs rephrasing, can you PTAL at the suggestions. Thank you. |
|
I rephrased using a mix of the suggested terms and my own formulations. Let me know if that's good. |
JeanMeche
added
the
action: cleanup
|
can you make sure to squash all the commits to satisfy the linter. Thank you. |
|
we still the squash into a single commit. |
|
You need me to squash all the commits into one, before squashing the commits when merging ? |
|
Yes, we only squash fixups and we want that change to be a single commit. |
|
Bump, this seems ready to ship |
JeanMeche
added
action: merge
|
Looks like we still have a formatting issue, can you PTAL. |
Co-authored-by: Matthieu Riegler <[email protected]>
JeanMeche
added
action: merge
3 participants
Clarify usage of Angular's ::ng-deep pseudo class and its implications for global styles.
This is a documentation-only change, that explains how
::ng-deepactually works, explaining in effect what was mentioned in #25160.I will also be proposing a change to the discouragement line - though I expect it will require more discussion since it explicitly engages "the Angular team" - to only discourage CSS rules where
::ng-deepappears at the start of the rule / applies to the whole selector.In my view, it is perfectly useful and legitimate to want a component to have style authority on both its template and the children that it's provided with. It's even less drastic than the other ViewEncapsulation modes.