NgtPortal

NgtPortal component allows you to create an off-screen buffer to render secondary scenes. This is particularly useful for creating effects like HUDs, mini-maps, or any scenario where you need to render things to a separate scene then combine it with your main scene graph.

Usage

NgtPortal requires a [container] input, usually a THREE.Scene, to render the content into. Optionally, you can pass in some initial [state] to configure the portal’s behavior.

1
export interface NgtPortalState extends Omit<NgtState, 'events'> {
2
    events: {
3
        enabled?: boolean;
4
        priority?: number;
5
        compute?: NgtComputeFunction;
6
        connected?: any;
7
    };
8
}

Check out Store section for details on NgtState.

1
import { NgtPortal } from 'angular-three';
2

3
@Component({
4
    template: `
5
        <ngt-portal [container]="container">
6
            <ng-template portalContent>
7
                <!-- things to render in the portal -->
8
            </ng-template>
9
        </ngt-portal>
10
    `,
11
    imports: [NgtPortal]
12
})
13
export class MyCmp {}

Auto Rendering

By default, NgtPortal does not automatically render the portal content and leaves that up to the consumers to decide when and where to render it.

To automatically render the portal content, you can use NgtPortalAutoRender directive that attaches on the <ngt-portal> component.

1
import { NgtPortal, NgtPortalAutoRender } from 'angular-three';
2

3
@Component({
4
    template: `
5
        <ngt-portal [container]="container" autoRender>
6
            <ng-template portalContent>
7
                <!-- things to render automatically in the portal -->
8
            </ng-template>
9
        </ngt-portal>
10
    `,
11
    imports: [NgtPortal, NgtPortalAutoRender]
12
})
13
export class MyCmp {}

NgtPortalAutoRender accepts a [autoRender] input to determine the render priority of the portal content (default to 1).

Priority 1: Clears and renders the main scene first
Priority > 1: Renders the portal content on top without clearing

How it works

NgtPortal creates a layered store that provides its own:

Scene
Pointer
Raycaster
Event handling
Viewport calculations

This ensures that components within the portal operate independently from the main scene while maintaining access to the store with the correct context (root or portal) when use injectStore. This allows you to reuse the component under different contexts whether it’s in the main scene graph or in the secondary scene graphs.

For many cases, the portal content is rendered to a THREE.WebGLRenderTarget and NgtPortal leaves that to you to render that target anywhere you want.

For practical examples, check out the Portals guide