Composing Host Behaviors

## What `hostDirectives` is A **directive** in Angular adds behaviour to an element: classes, attributes, listeners, state. Normally a template applies it by matching its selector, as in `<button appTooltip>`. The **directive composition API**, introduced in Angular 15, lets a component or directive apply directives to its **own host element** from inside its class, through the `hostDirectives` property of `@Component` or `@Directive`. Those directives are called **host directives**. ```ts @Component({ selector: 'app-menu-item', template: '<ng-content />', hostDirectives: [Tooltip, FocusRing], }) export class MenuItem {} ``` Every `<app-menu-item>` now carries a `Tooltip` and a `FocusRing`, without any template writing `appTooltip` or `appFocusRing`. ## What Angular does at runtime When Angular renders `<app-menu-item>`: 1. It creates an instance of each host directive, in addition to the `MenuItem` component instance, all on the same host element. 2. It applies each host directive's **host bindings and listeners** to that element, so the tooltip's `mouseenter` listener and the focus ring's class binding take effect. 3. It runs the host directives' **lifecycle hooks**, just as for directives matched in a template. 4. It makes the instances available to **dependency injection**, so `MenuItem` can `inject(Tooltip)`, and a host directive can inject the component. The host directive's **selector is ignored**: it is applied because the component lists it, not because an attribute matched. A directive meant only for composition can omit the selector entirely. ## Inputs and outputs are opt-in The part candidates most often get wrong: a host directive's inputs and outputs are **not** exposed on the component by default. If `Tooltip` has an input `text`, then `<app-menu-item text="Archive">` does not reach it. To expose it, expand the entry: ```ts hostDirectives: [{ directive: Tooltip, inputs: ['text'], outputs: ['shown'] }] ``` This design keeps the component's **public API deliberate**. Composing a behaviour does not silently widen what consumers can bind, and the component author chooses what becomes part of the contract. ## Constraints | Rule | Consequence | | --- | --- | | Applied statically at compile time | You cannot add or remove host directives at runtime | | Must be standalone | A directive declared with `standalone: false` is rejected | | Cannot be a component | Only directives can be host directives | | Selector is ignored | The directive applies whether or not an attribute is present | | Inputs and outputs are hidden by default | List them in `inputs` and `outputs` to expose them | Because directives are standalone by default since v19, the second rule rarely bites in new code, but it does when composing older NgModule-declared directives. ## Common misconceptions - **"It wraps the component."** Nothing is wrapped and no extra element appears; the directives and the component share one host element. - **"It renders the directive's template."** Directives have no template; host directives contribute host bindings, listeners, state and DI, not markup. - **"Consumers can bind any input of the composed directive."** Only the inputs listed in the entry are reachable from templates. - **"The directive must be written specially for composition."** Any standalone directive works; a selector-less directive is just the most common shape for behaviours meant only to be composed. - **"It costs a wrapper component per behaviour."** Each host directive is one extra class instance on the same element, with no extra DOM. ## A quick mental test To predict what a host directive does, imagine the component's selector element with the directive's attribute added by hand in every template, minus the ability to bind its inputs and outputs unless the component lists them. Everything else, including host bindings, lifecycle hooks and injection, behaves the same way. ## Why it exists Before this API, attaching shared behaviour to many components meant one of three things: asking every consumer to add attributes, a base class the component extends, or duplicating host bindings in each component. `hostDirectives` gives a fourth option: the component itself declares which reusable behaviours it is made of, and each stays an independent, testable directive with its own state.