Solvedangular Document what is <ng-content> tag and how content projection works

I'm submitting a ...

[ ] Regression (behavior that used to work and stopped working in a new release)
[ ] Bug report 
[ ] Feature request
[x] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead see https://github.com/angular/angular/blob/master/CONTRIBUTING.md#question

Current behavior

As per angular/angular.io#3099 searching for ng-content on https://angular.io/docs/ts/latest/ doesn't produce any useful results and there doesn't seem to be any detailed description about what it is and how it works.

Expected behavior

As per angular/angular.io#3099 these points should probably be documented:

  • projection just moves nodes from one place to another, which leads to following conclusions:
    • not possible to use projected content multiple times (link)
    • projected nodes/components, will be always created, even if you wrap them into *ngIf, e.g: <div *ngIf="false"><ng-content></ng-content></div>. It is reason for problems in #13760 and #13921. (link)
    • when using ViewEncapsulation.Emulated (and probably Native as well?) projected nodes will have encapsulation of the place, where they were created and not where, they are projected
  • how to query only subset of nodes using <ng-content select="<selector>">
    • document, that only top-level nodes can be selected by this approach
  • document a recipe with template, Tobias referring here to created projected nodes only when they are needed

Minimal reproduction of the problem with instructions

Search for ng-content on https://angular.io/docs/ts/latest/

What is the motivation / use case for changing the behavior?

It creates a lot of confusion for users, see:

Please tell us about your environment

N/A

26 Answers

✔️Accepted Answer

If it helps, I just published a blog post explaining the various edge cases of <ng-content>: https://medium.com/claritydesignsystem/ng-content-the-hidden-docs-96a29d70d11b
We needed it for our own documentation to explain to our consumers why we are using so many structural directives in our APIs.

Some of it can serve as a starting point for the future docs, feel free to use anything you want or like in there. 👍

Other Answers:

Please, Angular team document this.

Hi everyone!

I know this issue has been a long time coming. I have finally created a PR to provide (or start to provide, perhaps) documentation for content projection in Angular. It's currently available here: #41143.

There were some competing priorities when I joined the team last year; but I'm still sorry this has taken so long. And, FWIW, I found @youdz medium article fantastic!

This is very much on the docs team's radar. Please add your 👍 to the OP to indicate your support for documenting this.

This issue is 5 days older than my firstborn daughter. Also GoT season 7 was not even out then.
A lot of expectations were set, but this ticket still has not delivered.

@emilio-martinez

Not sure what makes you draw that conclusion 🤔

Well I was obviously exaggerating. My point was that one of the possible reasons not many people seemed to care about missing documentation is that there aren't many (new) developers picking up Angular in the first place.

I'm also very skeptical about your reasoning why it's not documented. I usually have to explaining why it's not a good idea to mix jQuery and Angular. I doubt a lot of people picking up Angular are familiar with Shadow DOM. And let's be honest here, Web Components isn't really a hit these days.

Now it's clear that Angular is "losing" to both React and soon Vue.js .. I know it's not a beauty pageant. But knowing that Angular is what Google is going with internally and has a lot invested I would not be surprised that their main focus is to have a good framework for their internal needs and documenting for the public is not a priority.

I don't want to say here that Angular is a bad framework or is going in a wrong direction. But I would expect a better effort from the team on developing the official docs.

More Issues: