@ngx-3d/viewport

A powerful Angular library for integrating THREE.js 3D graphics into your Angular applications with ease. Built with Angular 20+ and THREE.js, this library provides a declarative, component-based approach to creating 3D scenes.

🚀 Features

• Declarative Components: Use Angular components to define 3D elements in your templates
• Reactive State Management: Built on @ngrx/signals for efficient state updates
• Animation Support: Easy-to-use animation system for 3D objects
• Light Management: Simple API for adding and managing lights
• Model Loading: Support for loading GLTF/GLB 3D models
• Responsive Rendering: Automatic viewport handling and responsive design
• TypeScript: Full TypeScript support with type definitions
• Tree-shakeable: Optimized bundle size with specific THREE.js imports

📦 Installation

npm install @ngx-3d/viewport three
npm install --save-dev @types/three

Or using yarn:

yarn add @ngx-3d/viewport three
yarn add --dev @types/three

Or using pnpm:

pnpm add @ngx-3d/viewport three
pnpm add -D @types/three

🎯 Quick Start

1. Import the provider in your app configuration

import { ApplicationConfig } from '@angular/core';
import { provideN3DViewport } from '@ngx-3d/viewport';

export const appConfig: ApplicationConfig = {
  providers: [
    provideN3DViewport()
  ]
};

2. Use the components in your template

import { Component } from '@angular/core';
import { N3DElementComponent } from '@ngx-3d/viewport';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [N3DElementComponent],
  template: `
    <n3d-element
      [modelPath]="'assets/models/scene.glb'"
      [autoRotate]="true"
      [cameraPosition]="{ x: 0, y: 5, z: 10 }"
    />
  `
})
export class AppComponent {}

📚 Components

N3DElementComponent

The main component for rendering 3D models:

<n3d-element
  [modelPath]="'assets/models/model.glb'"
  [scale]="2"
  [position]="{ x: 0, y: 0, z: 0 }"
  [rotation]="{ x: 0, y: Math.PI / 4, z: 0 }"
  [autoRotate]="true"
  [rotationSpeed]="1"
  [cameraPosition]="{ x: 0, y: 5, z: 10 }"
  [enableZoom]="true"
  [enablePan]="true"
  [lights]="['directional', 'ambient']"
/>

N3DPlaneComponent

Add ground planes and surfaces:

<n3d-plane
  [width]="100"
  [height]="100"
  [color]="0x999999"
  [receiveShadow]="true"
/>

🎨 State Management

Access the reactive state store:

import { inject } from '@angular/core';
import { N3DViewportStore } from '@ngx-3d/viewport';

export class MyComponent {
  store = inject(N3DViewportStore);

  // Access reactive state
  scene = this.store.scene;
  camera = this.store.camera;
  renderer = this.store.renderer;
  
  // Get current values
  currentScene = this.store.scene();
}

🏗️ Development

Building the Library

cd projects/viewport
npm run build

Build artifacts will be placed in dist/ngx-3d-viewport/.

Development Mode

npm run build:watch

Publishing

1. Build the library:

   npm run build

2. Navigate to the dist directory:

   cd dist/ngx-3d-viewport

3. Publish to npm:

   npm publish

📋 Requirements

• Angular 20.3.0 or higher
• THREE.js 0.181.0 or higher
• @types/three (for TypeScript support)
• TypeScript 5.9.0 or higher

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License

🔗 Links

• Angular
• THREE.js
• Documentation