README.md

angular-three-tweakpane

This library provides Tweakpane integration for Angular Three, enabling easy creation of debug UI controls for tweaking parameters in your 3D scenes.

Documentation

All public APIs are documented with JSDoc comments. Your IDE will provide inline documentation, parameter hints, and examples as you code.

Installation

npm install angular-three-tweakpane tweakpane
# yarn add angular-three-tweakpane tweakpane
# pnpm add angular-three-tweakpane tweakpane

Make sure to already have angular-three installed

Usage

Declarative API with tweaks()

The recommended way to create controls:

1. Add tweakpaneAnchor directive to your ngt-canvas
2. Add <tweakpane-pane> somewhere in your scene
3. Use tweaks() in any component within the canvas

import { Component, ChangeDetectionStrategy, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { tweaks, TweakpaneAnchor, TweakpanePane } from 'angular-three-tweakpane';

@Component({
	template: `
		<ngt-mesh [position]="[params.x(), params.y(), params.z()]">
			<ngt-box-geometry />
			<ngt-mesh-standard-material [color]="params.color()" />
		</ngt-mesh>

		<tweakpane-pane title="Controls" />
	`,
	imports: [TweakpanePane],
	schemas: [CUSTOM_ELEMENTS_SCHEMA],
	changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SceneGraph {
	params = tweaks('Position', {
		x: { value: 0, min: -5, max: 5 },
		y: { value: 0, min: -5, max: 5 },
		z: { value: 0, min: -5, max: 5 },
		color: { value: '#ff0000', color: true },
	});
}

@Component({
	template: `
		<ngt-canvas tweakpaneAnchor>
			<app-scene-graph *canvasContent />
		</ngt-canvas>
	`,
	imports: [NgtCanvas, TweakpaneAnchor, SceneGraph],
})
export class Experience {}

Nested Folders

params = tweaks('Settings', {
	basic: 42,
	position: tweaks.folder('Position', {
		x: { value: 0, min: -5, max: 5 },
		y: { value: 0, min: -5, max: 5 },
		z: { value: 0, min: -5, max: 5 },
	}),
	material: tweaks.folder('Material', {
		color: { value: '#ff0000', color: true },
		metalness: { value: 0.5, min: 0, max: 1 },
		roughness: { value: 0.5, min: 0, max: 1 },
	}),
});

// Access nested values
this.params.position.x(); // Signal<number>
this.params.material.color(); // Signal<string>

Two-Way Binding with Existing Signals

filteringEnabled = signal(true);
gravity = signal(9.8);

params = tweaks('Settings', {
	filteringEnabled: this.filteringEnabled, // two-way binding
	gravity: this.gravity,
});

Buttons (Actions)

params = tweaks('Actions', {
	reset: { action: () => this.reset(), label: 'Reset All' },
	randomize: { action: () => this.randomize() },
});

Component-Based API

For more control, use individual components:

import {
	TweakpanePane,
	TweakpaneFolder,
	TweakpaneNumber,
	TweakpaneColor,
	TweakpaneCheckbox,
	TweakpaneButton,
} from 'angular-three-tweakpane';

@Component({
	template: `
		<tweakpane-pane title="Controls">
			<tweakpane-folder title="Position">
				<tweakpane-number [(value)]="x" label="X" [params]="{ min: -5, max: 5 }" />
			</tweakpane-folder>
			<tweakpane-color [(value)]="color" label="Color" />
			<tweakpane-checkbox [(value)]="visible" label="Visible" />
			<tweakpane-button title="Reset" (click)="reset()" />
		</tweakpane-pane>
	`,
	imports: [TweakpanePane, TweakpaneFolder, TweakpaneNumber, TweakpaneColor, TweakpaneCheckbox, TweakpaneButton],
})
export class Controls {
	x = signal(0);
	color = signal('#ff0000');
	visible = signal(true);

	reset() {
		this.x.set(0);
		this.color.set('#ff0000');
		this.visible.set(true);
	}
}

Control Types

Component	Description	Config Type
TweakpaneNumber	Numeric input with optional slider	{ value, min?, max?, step? }
TweakpaneText	Text input	{ value }
TweakpaneCheckbox	Boolean toggle	{ value }
TweakpaneColor	Color picker	{ value, color: true }
TweakpaneList	Dropdown select	{ value, options: [...] }
TweakpanePoint	2D/3D/4D point input	{ value, x?, y?, z?, w? }
TweakpaneButton	Clickable button	{ action: () => void, label? }
TweakpaneFolder	Collapsible group	tweaks.folder(name, config)

Pane Positioning

<tweakpane-pane title="Debug" top="8px" right="8px">
  <!-- controls -->
</tweakpane-pane>

Available position inputs: top, right, bottom, left, width