Components

A component is an ordinary TypeScript class with @Component({...}) on top. The decorator is how you hand Angular the information a plain class doesn't have: which HTML element it controls (selector), what it renders (template), what that template uses (imports), and how it's styled (styles). The class holds the state and behaviour; the decorator's object — the metadata — tells Angular how to turn that class into something on screen.

@Component is a TypeScript decorator: a function that is applied to the class when the class is defined (classes themselves are covered on the TypeScript site). But Angular's decorators are unusual. You might expect the decorator to run in the browser and register the class somewhere. It doesn't. The Angular compiler reads the decorator at build time, compiles the template, and replaces the decorator with static fields on the class. By the time the code reaches the browser, the decorator is effectively gone.

A mental model: the decorator is a build order form stapled to the class. The compiler reads the form, builds the parts (a factory that creates instances, and compiled template instructions), bolts them onto the class, and throws the form away.

import { Component, input } from '@angular/core';
import { UpperCasePipe } from '@angular/common';

@Component({
  selector: 'app-user-card',
  imports: [UpperCasePipe],
  template: `
    <h3>{{ name() | uppercase }}</h3>
    <p>{{ role() }}</p>
  `,
  styles: `h3 { margin: 0; }`,
  host: { class: 'card' },
})
export class UserCard {
  readonly name = input.required<string>();
  readonly role = input('Developer');
}

var UserCard = class _UserCard {
  name = input.required(/* debugName */);
  role = input("Developer", /* debugName */);
  static ɵfac = function UserCard_Factory(__ngFactoryType__) {
    return new (__ngFactoryType__ || _UserCard)();
  };
  static ɵcmp = i0.ɵɵdefineComponent({ type: _UserCard, selectors: [["app-user-card"]],
    hostAttrs: [1, "card"], inputs: { name: [1, "name"], role: [1, "role"] },
    decls: 5, vars: 4,
    template: function UserCard_Template(rf, ctx) {
      if (rf & 1) {
        i0.ɵɵdomElementStart(0, "h3");
        i0.ɵɵtext(1);
        i0.ɵɵpipe(2, "uppercase");
        i0.ɵɵdomElementEnd();
        i0.ɵɵdomElementStart(3, "p");
        i0.ɵɵtext(4);
        i0.ɵɵdomElementEnd();
      }
      if (rf & 2) {
        i0.ɵɵadvance();
        i0.ɵɵtextInterpolate(i0.ɵɵpipeBind1(2, 2, ctx.name()));
        i0.ɵɵadvance(3);
        i0.ɵɵtextInterpolate(ctx.role());
      }
    },
    dependencies: [UpperCasePipe],
    styles: ["\nh3[_ngcontent-%COMP%] {\n  margin: 0;\n}"] });
};
// …plus, only when ngDevMode is on: ɵsetClassMetadata(UserCard, [{ type: Component, args: [{…}] }])

const mirror = reflectComponentType(UserCard)!;
mirror.selector;      // 'app-user-card'
mirror.isStandalone;  // true
mirror.inputs;        // [{ propName: 'name', templateName: 'name', isSignal: true }, { propName: 'role', … }]
Object.getOwnPropertyNames(UserCard).filter((k) => k.startsWith('ɵ')); // ['ɵfac', 'ɵcmp']

The selector is a CSS selector that tells the compiler where to create a component: on every element in a template, among the ones that imported it, that matches. It uses ordinary CSS selector syntax, but only the parts that can be checked against a single element. The .d.ts lists what's supported: element name, .class, [attribute], [attribute=value], :not(…), and comma-separated alternatives — and nothing that "crosses element boundaries" (no descendant or child combinators).

From my notes: the square brackets ("rectangular bracket" in my notes) in a selector like [appCallout] mean an attribute selector, exactly as in CSS — "any element that has an appCallout attribute".

@Component({ selector: 'app-badge', template: `[badge]` })
export class Badge {}

@Component({ selector: '[appCallout]', template: `Note: <ng-content />` })
export class Callout {}

@Component({ selector: 'button[appPrimary]', template: `<ng-content />`, host: { class: 'primary' } })
export class PrimaryButton {}

@Component({ selector: '.app-chip', template: `[chip]` })
export class Chip {}

@Component({
  selector: 'app-selector-demo',
  imports: [Badge, Callout, PrimaryButton, Chip],
  template: `
    <app-badge />
    <div appCallout>Save often</div>
    <button appPrimary>Save</button>
    <a appPrimary>Not a button</a>
    <span class="app-chip"></span>
    <span [class.app-chip]="true"></span>
  `,
})
export class SelectorDemo {}

<app-badge>[badge]</app-badge>
<div appcallout="">Note: Save often</div>
<button appprimary="" class="primary">Save</button>
<a appprimary="">Not a button</a>
<span class="app-chip">[chip]</span>
<span class="app-chip"></span>

From my notes: "Host Element (Very important)". The host element is the DOM element that a component is attached to — the <app-toggle> in the parent's template. It belongs to both worlds: the parent creates it (it's in the parent's template, and the parent can put attributes, classes and bindings on it), and the component owns everything inside it (its template renders as the host's children) and can also control the host's own attributes, classes, styles and events.

Get this picture right and a lot falls into place: the component's template is not wrapped around the host — it goes inside it. There's no extra wrapper element unless you write one. :host in the component's CSS means "my host element". And when the component needs a click handler, an ARIA role or a CSS class on itself, it puts them on the host rather than on an inner <div>.

In modern Angular all of that goes in the host metadata object. Keys in quotes and brackets/parentheses mean the same as in templates: [prop] binds, (event) listens, a plain key is a static attribute.

@Component({
  selector: 'app-toggle',
  template: `{{ on() ? 'ON' : 'OFF' }}`,
  styles: `
    :host { display: inline-block; padding: 4px 8px; border: 1px solid; }
    :host(.is-on) { background: lightgreen; }
  `,
  host: {
    role: 'switch',
    tabindex: '0',
    '[class.is-on]': 'on()',
    '[attr.aria-checked]': 'on()',
    '(click)': 'toggle()',
    '(keydown.space)': 'toggle(); $event.preventDefault()',
  },
})
export class Toggle {
  protected readonly on = signal(false);
  toggle() {
    this.on.update((v) => !v);
  }
}

<!-- parent template: <app-toggle class="big" /> -->
<app-toggle role="switch" tabindex="0" class="big" _nghost-ng-c1817490615="" aria-checked="false">OFF</app-toggle>

@Component({
  selector: 'app-legacy-toggle',
  template: `{{ on ? 'ON' : 'OFF' }}`,
})
export class LegacyToggle {
  on = false;
  @HostBinding('attr.role') role = 'switch';
  @HostBinding('class.is-on') get isOn() { return this.on; }
  @HostBinding('attr.aria-checked') get checked() { return this.on; }
  @HostListener('click') toggle() { this.on = !this.on; }
}

<app-legacy-toggle role="switch" aria-checked="false">OFF</app-legacy-toggle>
<app-legacy-toggle role="switch" aria-checked="true" class="is-on">ON</app-legacy-toggle>

My notes have this as "Component instance vs view" and "Component instantiated as a class", with a "nice explanation below". The distinction:

• The component instance is a normal JavaScript object — new Toggle() — holding state (on, count, injected services) and methods. There's one instance per host element.
• The view is what Angular builds from the template for that instance: the actual DOM nodes inside the host, plus Angular's bookkeeping about which node each binding writes to and which listeners call which methods. A component's view is created once and then updated many times.

The class never touches the view directly. The compiled template function receives the instance as ctx and reads from it (ctx.name() in the compiled output above). So "instance" is the data, "view" is the rendering of that data, and change detection is the process of re-running the template's update block against the instance.

@Component({
  selector: 'app-probe',
  template: `<span>{{ clicks() }}</span><button (click)="clicks.set(clicks() + 1)">+</button>`,
})
export class Probe {
  private readonly host: HTMLElement = inject(ElementRef).nativeElement;
  protected readonly clicks = signal(0);

  constructor() {
    probeLog.push(`constructor: host <${this.host.tagName.toLowerCase()}> has ${this.host.childNodes.length} child nodes`);
    afterNextRender(() =>
      probeLog.push(`afterNextRender: host innerHTML = ${this.host.innerHTML}`),
    );
  }
}

@Component({
  selector: 'app-probe-pair',
  imports: [Probe],
  template: `<app-probe /><app-probe />`,
})
export class ProbePair {}

constructor: host <app-probe> has 0 child nodes
constructor: host <app-probe> has 0 child nodes
-- createComponent returned
afterNextRender: host innerHTML = <span>0</span><button>+</button>
afterNextRender: host innerHTML = <span>0</span><button>+</button>
two instances? 2 | same object? false
rendered: <app-probe><span>2</span><button>+</button></app-probe><app-probe><span>1</span><button>+</button></app-probe>

new Probe();
// NG0203: The `ElementRef` token injection failed. `inject()` function must be called from an
// injection context such as a constructor, a factory function, a field initializer, or a
// function used with `runInInjectionContext`.

A component becomes a child simply by being used in another component's template: if TodoList's template contains <app-todo-item>, then each TodoItem created there is a child of that TodoList. That's the whole mechanism. The component tree is the result: the root component's template creates children, their templates create grandchildren, and so on. The tree mirrors the templates, not the file structure or the imports.

Three things follow from "each element in the parent template is a child":

1. One child instance per element. <app-todo-item> written three times, or inside an @for over three items, means three separate TodoItem instances, each with its own state.
2. The parent controls the child's existence. When an @if turns false or an @for item is removed, Angular destroys that child — instance, view and all.
3. Data flows along the tree. Parents pass data down with inputs and get events up with outputs (see Parent to child with input() and Child to parent with output()). Children don't reach into parents.

@Component({
  selector: 'app-todo-item',
  template: `<p>{{ text() }}</p>`,
})
export class TodoItem implements OnDestroy {
  readonly text = input.required<string>();
  constructor() {
    treeLog.push('TodoItem constructor');
  }
  ngOnDestroy() {
    treeLog.push(`TodoItem destroyed: ${this.text()}`);
  }
}

@Component({
  selector: 'app-todo-list',
  imports: [TodoItem],
  template: `
    <h2>{{ todos().length }} todos</h2>
    @for (todo of todos(); track todo) {
      <app-todo-item [text]="todo" />
    }
  `,
})
export class TodoList {
  readonly todos = signal(['Learn components', 'Learn signals']);
  constructor() {
    treeLog.push('TodoList constructor');
  }
}

TodoList constructor
-- createComponent returned
TodoItem constructor
TodoItem constructor
-- first render done
TodoItem constructor
-- added one
TodoItem destroyed: Learn components
-- removed one
<h2>2 todos</h2><app-todo-item><p>Learn signals</p></app-todo-item><app-todo-item><p>Learn DI</p></app-todo-item>
after fixture.destroy(): TodoItem destroyed: Learn signals | TodoItem destroyed: Learn DI

From my notes: "Component vs Directive" and "Some more info on directives". A directive is a class that Angular attaches to an element matched by its selector, to add behaviour: it can bind to the element's properties, attributes, classes and styles, listen to its events, and take inputs. A component is a directive with a template — the .d.ts says it literally: interface Component extends Directive. Everything a directive can do (selector, inputs, outputs, host, providers) a component can do too; the component adds its own view.

That one difference drives the rest:

The "one component per element" rule exists because a component owns the element's content: two templates can't both render into the same host. Directives don't render content, so they can stack.

@Directive({
  selector: '[appTint]',
  host: { '[style.backgroundColor]': 'color()' },
})
export class Tint {
  readonly color = input('yellow', { alias: 'appTint' });
}

@Directive({
  selector: '[appTrim]',
  host: { '(blur)': 'trim()' },
})
export class Trim {
  private readonly input: HTMLInputElement = inject(ElementRef).nativeElement;
  trim() {
    this.input.value = this.input.value.trim();
  }
}

@Component({
  selector: 'app-directive-demo',
  imports: [Tint, Trim, Badge],
  template: `
    <p appTint="lightyellow">tinted paragraph</p>
    <p appTint>bare attribute</p>
    <input appTint="pink" appTrim value="  spaced  " />
    <app-badge appTint="lightblue" />
  `,
})
export class DirectiveDemo {}

<p apptint="lightyellow" style="background-color: lightyellow;">tinted paragraph</p>
<p apptint="">bare attribute</p>
<input apptint="pink" apptrim="" value="  spaced  " style="background-color: pink;">
<app-badge apptint="lightblue" style="background-color: lightblue;">[badge]</app-badge>

A component's template can be written inline in the decorator (template: `…`) or in a separate file (templateUrl: './greeting.html'). Styles likewise: styles inline, or styleUrl (one file) / styleUrls (several). It's purely a source-organisation choice — the compiler inlines external files at build time, so the compiled component is identical either way and there's no extra HTTP request at runtime.

// External: template and styles in their own files.
@Component({
  selector: 'app-greeting',
  templateUrl: './greeting.html',
  styleUrl: './greeting.css',
})
export class Greeting {
  protected readonly name = signal('Rohit');
}

// Inline: the same component in one file.
@Component({
  selector: 'app-greeting-inline',
  template: `<p class="greeting">Hello, {{ name() }}!</p>`,
  styles: `.greeting { font-weight: bold; }`,
})
export class GreetingInline {
  protected readonly name = signal('Rohit');
}

<p class="greeting">Hello, {{ name() }}!</p>

external: <p _ngcontent-a-c3877310805="" class="greeting">Hello, Rohit!</p>
inline:   <p _ngcontent-a-c2595531065="" class="greeting">Hello, Rohit!</p>

By default, CSS you write in a component applies only to that component's own template. A .msg { color: red } in one component won't turn another component's .msg red, even though CSS is normally global. Angular does this with view encapsulation, set per component with encapsulation:

• ViewEncapsulation.Emulated (default): the compiler rewrites every selector to also require a unique attribute, and Angular stamps that attribute on the elements of this component's template. Scoped styles, no Shadow DOM.
• ViewEncapsulation.None: styles are added to the page as written — global. They affect every matching element in the app.
• ViewEncapsulation.ShadowDom: Angular attaches a real shadow root to the host and renders the template and styles inside it, so the browser itself enforces the boundary. (22.2 also has ExperimentalIsolatedShadowDom, marked experimental, which additionally keeps other component styles out.)

A mental model for Emulated: every component gets a name tag. Its elements wear the tag (_ngcontent-ng-c123), its host wears a host tag (_nghost-ng-c123), and its CSS rules say "only elements wearing my tag".

@Component({
  selector: 'app-emulated',
  template: `<p class="msg">emulated</p>`,
  styles: `
    :host { display: block; }
    .msg { color: red; }
    :host ::ng-deep .msg { font-style: italic; }
  `,
})
export class Emulated {}

@Component({
  selector: 'app-unscoped',
  encapsulation: ViewEncapsulation.None,
  template: `<p class="msg">none</p>`,
  styles: `.msg { color: blue; }`,
})
export class Unscoped {}

@Component({
  selector: 'app-shadow',
  encapsulation: ViewEncapsulation.ShadowDom,
  template: `<p class="msg">shadow</p>`,
  styles: `.msg { color: green; }`,
})
export class Shadow {}

@Component({
  selector: 'app-encapsulation-demo',
  imports: [Emulated, Unscoped, Shadow],
  template: `
    <p class="msg">parent paragraph</p>
    <app-emulated />
    <app-unscoped />
    <app-shadow />
  `,
})
export class EncapsulationDemo {}

<p class="msg">parent paragraph</p>
<app-emulated _nghost-a-c3045686696=""><p _ngcontent-a-c3045686696="" class="msg">emulated</p></app-emulated>
<app-unscoped><p class="msg">none</p></app-unscoped>
<app-shadow></app-shadow>

[_nghost-a-c3045686696] { display: block; }
.msg[_ngcontent-a-c3045686696] { color: red; }
[_nghost-a-c3045686696]     .msg { font-style: italic; }
---
.msg { color: blue; }