Angular @boundary and Angular Three

Angular announced a proposed @boundary template block recently. At least at the time I am writing this, I would not treat it as a production API. The public shape is still early, and the details can change. This is not a tutorial.

This is more of a thought exercise from the perspective of Angular Three.

I maintain Angular Three, a THREE.js integration for Angular with declarative scene graph, componentized meshes, loader helpers, render loop hooks, and a helper package in angular-three-soba.

Resource is explicit

The nice thing about Angular’s Resource API is that it makes async state boring and visible. A consumer can look at a resource and decide what to do for each branch.

1
@if (model.hasValue()) {
2
    <app-car [model]="model.value()" />
3
} @else if (model.isLoading()) {
4
    <app-car-placeholder />
5
} @else if (model.error(); as error) {
6
    <app-car-error [error]="error" />
7
}

This is not as cute as Suspense, but it is very Angular. There is no hidden thrown promise, no implicit pause in the middle of rendering, and the template says exactly what happens when the resource is resolved, loading, or errored.

That explicitness also means each consumer gets to make its own choice. In one component tree, loading a car might render a wireframe proxy and an error marker. In another component tree, loading might render nothing and error might fall back to a static mesh. The Resource API does not prescribe the UI. It exposes the state and lets the consumer decide.

The awkward Angular Three version

Now put that in Angular Three. A car model usually starts with a path:

1
<app-car path="/models/car.glb" />

The obvious implementation is for app-car to own the GLTF resource.

1
import { Component, CUSTOM_ELEMENTS_SCHEMA, input } from '@angular/core';
2
import { NgtArgs } from 'angular-three';
3
import { gltfResource } from 'angular-three-soba/loaders';
4

5
@Component({
6
    selector: 'app-car',
7
    imports: [NgtArgs],
8
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
9
    template: `
10
        @if (model.hasValue()) {
11
            <ngt-primitive *args="[model.value().scene]" />
12
        } @else if (model.isLoading()) {
13
            <app-car-placeholder />
14
        } @else if (model.error(); as error) {
15
            <app-car-error [error]="error" />
16
        }
17
    `,
18
})
19
export class Car {
20
    path = input.required<string>();
21

22
    protected model = gltfResource(() => this.path());
23
}

This is fine at first glance. The component owns the path, the loading, the GLTF, and the rendering. Nice and encapsulated.

The problem is that app-car also owns the error UI now. Every consumer gets <app-car-error />. Maybe that is fine for a demo, but it is not always what I want in a real scene. In a product configurator, the error might be a branded fallback. In an editor, it might be a red debug object with the failed URL. In a background scene, I might want to render nothing.

Resource is explicit, but I accidentally hid the resource inside app-car, so the consumer lost the ability to choose the branches.

Push the resource up?

The pure Resource answer is to push the resource to the consumer and make app-car accept the loaded GLTF.

1
@if (car.hasValue()) {
2
    <app-car [model]="car.value()" />
3
} @else if (car.isLoading()) {
4
    <app-car-placeholder />
5
} @else if (car.error(); as error) {
6
    <app-car-error-in-showroom [error]="error" />
7
}

Then app-car becomes simpler:

1
export class Car {
2
    model = input.required<LoadedCarModel>();
3
}

I like the control this gives the consumer. I do not always like the shape it forces onto the component API. Now the consumer needs to know how to load the car. It needs the right loader helper, the right model type, maybe decoder setup, maybe preload behavior, maybe extra processing. The input type can also get awkward because a loaded GLTF is not the same thing as the thing the component conceptually wants to expose.

For a leaf component, this is okay. For a richer Angular Three component, it gets noisy. Imagine a car component that loads a body model, wheel variants, optional paint textures, maybe an interior model. Passing all of that in as fully loaded inputs keeps Resource control at the top, but it leaks a lot of implementation detail into the consumer.

There are other Angular answers like content projection, TemplateRef, or inputs for custom error templates. For the sake of theory-crafting, let’s pretend those are not the first things people reach for. They can become a lot of ceremony for something that conceptually feels simple: this car failed here, render this fallback here.

Where @boundary changes the tradeoff

This is where @boundary becomes interesting to me. With a boundary, app-car can own the Resource again. It can own the path, the loader, the model processing, and the success rendering. But when the Resource errors, app-car can choose to let that error escape instead of rendering its own error UI.

1
@boundary {
2
    <app-car path="/models/car.glb" />
3
} @error (let error) {
4
    <app-car-error-in-showroom [error]="error" />
5
}

Another consumer can do something else:

1
@boundary {
2
    <app-car path="/models/car.glb" />
3
} @error {
4
    <app-basic-car-proxy />
5
}

That is the premise I like: the component owns the Resource, but the consumer owns the error branch. @boundary does not know anything about the Resource. It only catches because app-car decides that a Resource error means “I cannot render this subtree”.

Conceptually, app-car becomes something like this:

1
@if (model.hasValue()) {
2
    <ngt-primitive *args="[model.value().scene]" />
3
} @else if (model.isLoading()) {
4
    <app-car-placeholder />
5
} @else if (model.error(); as error) {
6
    {{ throwError(error) }}
7
}

Ignore the throwError() syntax here. I completely pulled that out of my rear. The point is the responsibility split: Resource stays explicit inside the component, and the component explicitly turns the error branch into a render failure that a consumer boundary can handle.

That feels different from Suspense. Suspense says pending async work changes rendering. This says a component can decide that one explicit Resource branch is no longer locally recoverable.

Why this matters more in 3D

In a 3D scene, the difference between local error UI and consumer-owned error UI can change the meaning of the scene.

1
<app-lights />
2
<app-camera-rig />
3

4
@boundary {
5
    <app-car path="/models/car.glb" />
6
} @error {
7
    <app-missing-car-marker />
8
}
9

10
@boundary {
11
    <app-hdr-environment preset="studio" />
12
} @error {
13
    <app-default-studio-light />
14
}
15

16
<app-orbit-controls />

A failed car model should not necessarily take down the camera controls. A failed HDR environment should not necessarily blank the whole canvas. A failed material should maybe fall back to a debug material while the mesh stays alive.

The fallback is not always a panel or a toast. Often, the fallback is another 3D object.

That is probably the part that makes @boundary feel exciting for Angular Three. It lets the consumer define a failure domain in the same place they define the scene structure.

And because boundaries can be nested, a fallback can have its own fallback:

1
@boundary {
2
    <app-car path="/models/car.glb" />
3
} @error (let error) {
4
    @boundary {
5
        <app-rich-car-error [error]="error" />
6
    } @error {
7
        <app-basic-car-proxy />
8
    }
9
}

That matters in a scene graph. The error UI can be just as risky as the thing it replaces.

What about loading?

Error is the easier part. Loading is where the theory-crafting starts.

If @boundary is an error boundary, then loading should not magically move into it. A pending Resource is not an error; it is state, and Angular picked Resource specifically so that async state remains explicit. I do not want @boundary to smuggle Suspense back in.

So the conservative version is:

1
@boundary {
2
    <app-car path="/models/car.glb" />
3
} @error (let error) {
4
    <app-car-error-in-showroom [error]="error" />
5
}

app-car still owns its loading UI:

1
@if (model.isLoading()) {
2
    <app-car-placeholder />
3
}

This preserves Angular’s explicitness, but the consumer cannot customize the loading branch unless the component exposes some API for it, and maybe that is okay as loading feels like normal composition territory.

For example, app-car could expose a loading template:

1
<app-car path="/models/car.glb">
2
    <ng-template loading>
3
        <app-wireframe-car />
4
    </ng-template>
5
</app-car>

Or with a structural directive shorthand:

1
<app-car path="/models/car.glb">
2
    <app-wireframe-car *loading />
3
</app-car>

Same for a component-owned Resource error, if the component wants to keep errors local:

1
<app-car path="/models/car.glb">
2
    <app-car-loading *loading />
3
    <app-car-error *error="let error" [error]="error" />
4
</app-car>

That is just Angular composition. ng-template, content projection, structural directives, whatever API the component wants to expose. It is not as globally elegant as Suspense, but it keeps the contract explicit and component-owned.

The error case is still more interesting to me because @boundary is not only about Resource errors. It can also catch the unexpected stuff: a bad input assumption, a failed THREE object setup, a material component that throws, a bug in the subtree. That is different from a loading template.

Could Angular expose a better control-flow primitive for Resource? Maybe. Something like this would be nice to write:

1
@resource (model; let value) {
2
    <app-car [model]="value" />
3
} @loading {
4
    <app-car-loading />
5
} @error (let error) {
6
    <app-car-error [error]="error" />
7
}

But this gets suspense-y, even if the Resource is named and the branches are visible. Maybe that is fine. Maybe it is too much framework for something @if already handles. I am not sure.

@defer is not this either

Angular already has @defer, and @defer has @loading and @error blocks. That is useful, but it is a different kind of boundary.

1
@defer (on viewport) {
2
    <app-product-scene />
3
} @placeholder {
4
    <img src="/product-preview.webp" alt="Product preview" />
5
} @loading {
6
    <p>Loading 3D viewer...</p>
7
} @error {
8
    <p>Could not load the 3D viewer code.</p>
9
}

This is about loading the viewer code, not whether /models/car.glb loads, a texture fails, or app-car decides its Resource error should escape to a consumer-owned fallback.

You might compose them:

1
@defer (on viewport) {
2
    @boundary {
3
        <app-product-scene />
4
    } @error (let error) {
5
        <app-scene-error [error]="error" />
6
    }
7
} @placeholder {
8
    <img src="/product-preview.webp" alt="Product preview" />
9
} @error {
10
    <p>Could not load the 3D viewer code.</p>
11
}

That composition is probably powerful, but the distinction matters: @defer @error means deferred code failed, @boundary @error means the rendered subtree failed, and Resource error() means async data failed while the component still gets to decide what to do with that state.

Conclusion

For Angular Three, I think the useful mental model is this:

1
Resource owns async state.
2
Component owns whether that state is locally recoverable.
3
Boundary lets the consumer own unrecoverable UI for this usage.

That gives me a version of app-car that can stay encapsulated while still letting each scene choose its own failure UI:

1
@boundary {
2
    <app-car path="/models/car.glb" />
3
} @error {
4
    <app-car-fallback-for-this-scene />
5
}

Maybe Angular eventually gets a better Resource control-flow primitive. Maybe Angular Three grows a small helper for resource-owning scene components. Maybe the answer is still component APIs with TemplateRef. I am not sure yet.

What I am sure about is that error ownership matters a lot in 3D. A failed model, texture, environment, or postprocessing pass should not always decide its own fallback, and it should not take down the whole canvas. Put the boundary where the consumer can tolerate failure. In a 3D scene, that is rarely the whole canvas.

Thanks for reading, and have fun!