Content Projection with ng-content

Analogy categoryAnalogies

Content projection is Angular's mechanism for letting a component accept arbitrary markup from its parent and render it inside its own template, at a location the component controls. This is achieved with the <ng-content> tag, a placeholder that does not render an element itself but marks where projected content should be inserted. It's the Angular equivalent of React's children prop or Vue's default and named slots, and it's essential for building reusable structural components — cards, panels, modals, layout wrappers — whose exact inner content varies by usage but whose outer chrome (borders, headers, styling) stays consistent.

🏏

Cricket analogy: Content projection is like a stadium's hospitality box: the venue (component) provides the fixed structure — walls, seating, catering counter — but lets each corporate sponsor (parent) bring their own banners and decor to place inside, at the spot the box design allows.

Single-Slot Projection

In the simplest form, a component template includes a single, unqualified <ng-content /> tag. Anything placed between the component's opening and closing tags in the parent's template is projected wholesale into that slot. This is useful for generic wrapper components where the exact content doesn't need to be split into distinct regions — for example, a simple <app-panel> that just adds padding and a border around whatever is passed in.

🏏

Cricket analogy: A single unqualified <ng-content /> is like a generic team dugout bench: whatever players (any markup) sit on it get grouped together as-is, useful for a simple wrapper like a rain-delay shelter that doesn't need separate compartments for batsmen versus bowlers.

typescript

@Component({
  selector: 'app-panel',
  standalone: true,
  template: `
    <div class="panel">
      <ng-content />
    </div>
  `
})
export class PanelComponent {}

// Usage:
// <app-panel>
//   <p>Any markup goes here and is projected as-is.</p>
// </app-panel>

Multi-Slot Projection with the select Attribute

For more structured components, <ng-content> accepts a select attribute that acts as a CSS selector, routing matching elements from the parent's projected content into that specific slot instead of the default one. You can select by element tag name (select="app-card-header"), by attribute (select="[card-footer]"), or by CSS class (select=".card-icon"). Any content that doesn't match any select attribute falls through to a plain, unqualified <ng-content /> if one is present elsewhere in the template — otherwise it's discarded. Order of the ng-content tags in the component's template determines rendering order, not the order the content appears in the parent.

🏏

Cricket analogy: The select attribute is like a stadium's separate gates — Gate A for members (select="[card-footer]"), Gate B for general admission by ticket type (select=".card-icon") — where anyone without a matching ticket type funnels into the general overflow gate, or is turned away if none exists.

typescript

@Component({
  selector: 'app-card',
  standalone: true,
  template: `
    <div class="card">
      <header><ng-content select="[card-title]" /></header>
      <section class="body"><ng-content /></section>
      <footer><ng-content select="[card-footer]" /></footer>
    </div>
  `
})
export class CardComponent {}

// Usage:
// <app-card>
//   <h2 card-title>Order #1024</h2>
//   <p>Shipped on July 3rd.</p>
//   <button card-footer>Track</button>
// </app-card>

Content projected via ng-content is compiled in the context of the parent component, not the child — this is a crucial distinction from template rendering in general. That means bindings and event handlers inside projected content still resolve against the parent's component class, even though the markup visually appears inside the child's DOM structure, exactly analogous to how children in React close over the parent's scope, not the child component receiving them.

Because ng-content only projects content — it does not clone or re-render it — you cannot conditionally project content twice or repeat it inside a *ngFor/@for loop by re-using the same <ng-content> tag multiple times; only the first occurrence of a matching selector actually receives the projected nodes, and duplicate ng-content tags with the same selector receive nothing. For cases needing repeated or conditional reuse of a content template, use <ng-template> with TemplateRef and ngTemplateOutlet (or @ContentChild(TemplateRef)) instead.

Content projection composes well with @ContentChild and @ContentChildren (covered separately) when a component needs to programmatically inspect or interact with its projected content, such as validating that a required sub-element was provided, or coordinating state (like an active tab) among multiple projected children.

🏏

Cricket analogy: @ContentChild is like an umpire checking that a required piece of kit — say, a bowler's marked run-up cone — was actually placed on the field before play, or coordinating which of several fielders is currently the designated wicketkeeper.

<ng-content /> is a placeholder marking where a parent's projected markup renders inside a child component's template.
Single-slot projection captures all content between a component's opening and closing tags into one location.
The select attribute enables multi-slot projection, routing content matching a CSS-like selector (tag, attribute, or class) into distinct slots.
Unmatched projected content falls through to an unqualified <ng-content />, if present, or is otherwise discarded.
Projected content is compiled against the parent's component context, not the child's — bindings inside it resolve to the parent class.
ng-content only projects once; repeated or conditional reuse of content requires ng-template + ngTemplateOutlet instead.