Getting started
Angular Dynamic Hooks allows you to load Agular components into any dynamic content, such as HTML strings (similar to a “dynamic” template) or even already-existing HTML structures.
Works as part of an Angular app or fully standalone. Load components by selectors or any text pattern. No JiT-compiler required - just install and go.
Installation
Simply install via npm (or yarn)
npm install ngx-dynamic-hooks
See the Quickstart page for an example on how to get going right away.
| Angular | Version | NPM |
|---|---|---|
| 6 - 12 | 1.x.x | ngx-dynamic-hooks@^1 |
| 13-16 | 2.x.x | ngx-dynamic-hooks@^2 |
| 17+ | 3.x.x | ngx-dynamic-hooks@^3 |
As the library does not rely on a runtime compiler, it works in both JiT- and AoT-environments.
Upgrading to v3
If you have been using v2 of the library and are looking to upgrade, have a look at Version 3 - What's new? for a list of breaking changes.Highlights
- ⭐ Loads fully-functional Angular components into dynamic content
- 📖 Parses both strings and HTML trees to load components into them like a template
- 🚀 Can be used fully standalone (load components directly into HTML without Angular)
- 🏃 Works without needing the JiT compiler
- 💻 Works with Server-Side-Rendering
- 🔍 Loads components by their selectors, custom selectors or any text pattern of your choice
- ⚙️ Services, Inputs/Outputs, Lifecycle Methods and other standard features all work normally
- 💤 Allows lazy-loading components only if they appear in the content
- 🔒 Can pass custom data safely to your components via an optional context object
Load components dynamically
In Angular, you normally load components by placing their selectors in a template. But what if you wanted to load components not just from static templates, but from arbitrary dynamic content as well - such as string variables, HTML elements or even the whole browser DOM?
By default, this is not easily possible.
Angular Dynamic Hooks solves this shortcoming by allowing you to load components from any content of your choice at runtime - similar to a “dynamic template”. The library does not need the Just-in-Time Angular compiler to do so, resulting in much smaller bundle sizes.
It is able to do all this in a controlled and secure manner by using so-called hooks.
What’s a hook?
Simply put, hooks are any HTML element or text pattern in the content to be replaced by an Angular component.
Hooks can be singletags (<hook>) or enclosing (<hook>...</hook>). In most cases, you may simply want to use the normal component selectors as their hooks. You can easily do that with the out-of-the-box SelectorHookParser that comes included with this library.
Just use your selectors like in a normal Angular template (such as <app-mycomponent [someInput]="'hello!'">...</app-mycomponent>) and the corresponding components will be loaded in their place.
What is especially neat: Hooks can be anything - not just component selectors!
Each hook internally has a corresponding HookParser that tells the library where and how to instantiate the component. You can easily create your own hook parsers that replace any HTML element or text pattern of your choice with Angular components!
Do the components work normally?
Yes, the dynamically-loaded components are fully-functional as they are created with native Angular methods. They seamlessly integrate into the rest of the app with all features working as expected, such as:
- @Inputs()
- @Outputs()
- Content projection / transcluded content
- Change detection
- Dependency injection / services
- All lifecycle methods
You can even lazy-load components only when they appear in the content to minimize the initial bundle size.
For more details about all of these topics, see the following sections.
What this library doesn’t do
Please note that this library does not aim to be a full Angular template compiler. It implements its own parsing logic that specifically looks for registered hooks and replaces them with their corresponding Angular components - nothing more.
This means that other special Angular template syntax (such as *ngIf, *ngFor or other directives) will not work.
However, in terms of loading components, it allows for a lot more flexibility and possibilities than Vanilla Angular itself, such as allowing you to load them at runtime from normal strings or HTML trees, replacing text patterns with components and more.