[](https://www.npmjs.com/package/@ngneat/overview)
[](https://github.com/ngneat/overview/blob/main/LICENSE)
[](http://commitizen.github.io/cz-cli/)
[](https://github.com/ngneat/overview/pulls)
[](https://github.com/prettier/prettier)
[](#contributors-)
[](https://github.com/ngneat/)
[](https://github.com/ngneat/spectator)
> Overview - The Template for Success in Template Management
## Compatibility with Angular Versions
| @ngneat/overview |
Angular |
|
6.x
|
>= 17
|
|
5.x
|
>= 16
|
|
4.x
|
>= 14 < 16
|
|
3.x
|
>= 13 < 14
|
|
2.x
|
>= 11 < 13
|
## Installation
```bash
npm install @ngneat/overview
yarn add @ngneat/overview
pnpm install @ngneat/overview
```
## Table of Contents
- [DynamicView](#DynamicContent)
- [Teleporting](#Teleporting)
- [ViewService](#ViewService)
- [createView](#createView)
- [createComponent](#createComponent)
- [createTemplate](#createTemplate)
## `DynamicView`
Use the `dynamicView` structural directive to render a component, a template, HTML, or default template dynamically.
Let’s say we build a generic error component. What we want is to give our consumers the flexibly to create it by using one of three options:
- They can choose to use the default template
- They can choose to use their own text which can be static or dynamic
- They can choose to pass their own template or component
```ts
import { DynamicViewDirective, Content } from '@ngneat/overview';
@Component({
template: ` Default view
`,
standalone: true,
imports: [DynamicViewDirective],
})
export class ErrorComponent {
@Input() view: Content | undefined;
}
```
You can also pass a `context` or an [`injector`](https://angular.io/api/core/Injector) as `inputs` to the directive:
```html
Component
Template
{{ title }}
```
If you pass `context` to a component and the value can be accessed via the `injectViewContext` function:
```ts
import { injectViewContext } from '@ngneat/overview';
interface Context {
title: string;
}
@Component({
template: `{{ context().title }}
`,
standalone: true,
})
export class MyDynamicComponent {
context: Signal = injectViewContext();
}
```
`injectViewContext` returns a readonly signal with the view's context object.
## `Teleporting`
Teleporting means rendering a view at a different location from its declaration. There are two cases it might be helpful:
- Avoid prop drilling to a nested component.
- Rendering a view at another place in the DOM while keeping its context where it’s defined.
You can read more about this approach in this [article](https://netbasal.com/beam-me-up-scotty-on-teleporting-templates-in-angular-a924f1a7798).
Use the `teleportOutlet` directive to define a new `outlet`. An `outlet` is an anchor where the view will be projected as a sibling.
```typescript
import { TeleportOutletDirective } from '@ngneat/overview';
@Component({
template: `
`,
standalone: true,
imports: [TeleportOutletDirective],
})
export class FooComponent {}
```
Use the `teleportTo` directive to `teleport` the view to a specific `outlet`:
```typescript
import { TeleportDirective } from '@ngneat/overview';
@Component({
template: `
`,
standalone: true,
imports: [TeleportDirective],
})
export class BarComponent {
value = '...';
}
```
### Testing Teleported Components
When the outlet and the teleporting content live in different components (the common real-world case), the trick is to declare both components in the same test and render the parent that hosts the outlet.
```ts
import { Component } from '@angular/core';
import { provideZonelessChangeDetection } from '@angular/core';
import { createComponentFactory } from '@ngneat/spectator';
import { TeleportDirective, TeleportOutletDirective } from '@ngneat/overview';
// The shell that owns the outlet — mirrors your real AppComponent / layout.
@Component({
selector: 'app-shell',
template: `
`,
imports: [TeleportOutletDirective],
})
class ShellComponent {}
// The page that teleports content into the outlet.
@Component({
template: `
My Page
Page body
`,
imports: [ShellComponent, TeleportDirective],
})
class PageComponent {}
describe('PageComponent', () => {
const createComponent = createComponentFactory({
component: PageComponent,
providers: [provideZonelessChangeDetection()],
});
it('should teleport the title into the shell header', () => {
const spectator = createComponent();
expect(spectator.query('header')).toHaveText('My Page');
});
});
```
The key points:
- **Render the page component**, not the shell — the page is the unit under test.
- **Import the shell** inside the page's `imports` array so Angular compiles both together. Both the `teleportOutlet` and `*teleportTo` directives are active in the same test.
- Both outlets register before the `*teleportTo` subscribes. This is safe — the service checks current ports on subscription, so no events are missed regardless of registration order.
## ViewService
The `ViewService` provides `facade` methods to create modular views in Angular. It's been used in various projects like [hot-toast](https://github.com/ngneat/hot-toast), and [helipopper](https://github.com/ngneat/helipopper).
### `createComponent`
The `createComponent` method takes a `Component`, and returns an instance of `CompRef`:
```ts
import { ViewService, CompRef } from '@ngneat/overview';
@Injectable()
class ToastService {
private viewService = inject(ViewService);
componentRef: CompRef;
init() {
this.componentRef = this.viewService
.createComponent(HotToastContainerComponent)
.setInput('defaultConfig', defaultConfig)
.appendTo(document.body);
}
}
```
There are cases where we want to use an Angular [component](https://netbasal.com/using-angular-components-with-third-party-libraries-522a1f33003) template in a third-party library that takes a native DOM element or a string. In this case, we can use the `getRawContent` or the `getElement` method, respectively.
```ts
import { ViewService } from '@ngneat/overview';
@Directive()
class ChartDirective {
private viewService = inject(ViewService);
createChart(color: string) {
const ref = this.viewService.createComponent(FooTooltip).setInput('color', color).detectChanges(document.body);
const content = ref.getRawContent();
ref.destroy();
Highcharts.chart('container', {
tooltip: {
formatter: function () {
return content;
},
useHTML: true,
},
});
}
}
```
#### `createComponent` Options
```ts
createComponent(component: Type, {
injector?: Injector,
environmentInjector?: EnvironmentInjector,
context?: Context,
vcr?: ViewContainerRef,
})
```
### `createTemplate`
The `createTemplate` method takes a `TemplateRef`, and returns an instance of `ViewRef`.
```ts
createTemplate(tpl: TemplateRef, {
context?: Context,
vcr?: ViewContainerRef,
injector?: Injector,
})
```
### `createView`
The `createView` method takes a `Component`, a `TemplateRef` or a `string`, and creates a `View`:
```ts
import { ViewService, Content } from '@ngneat/overview';
@Injectable()
class ToastService {
private viewService = inject(ViewService);
createToast(content: Content) {
const ref = this.viewService.createView(content);
document.body.appendChild(ref.getElement());
}
}
```
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
