configureGizmo

configureGizmo

Configure the interactive transform gizmo - translate, rotate, and scale handles shown in the viewport.

Signature

configureGizmo(options: GizmoOptions): Promise<GizmoState>

Parameters

Parameter	Type	Required	Description
options	GizmoOptions	Yes	Partial options to apply

GizmoOptions

type GizmoOptions = {
  enabled?: boolean;       // Show/hide the gizmo
  advancedMode?: boolean;  // Show plane handles (TXY, TYZ, TZX, SXY, SYZ, SZX)
  localSpace?: boolean;    // Use local orientation instead of world
  snap?: {
    enabled?: boolean;       // Master snap toggle
    grid?: boolean;          // Grid snapping for translation
    angle?: boolean;         // Angle snapping for rotation
    gridResolution?: number; // Grid size in scene units (e.g., 0.5)
    angleParam?: number;     // Angle increment in degrees (e.g., 15)
    toFace?: boolean;        // Snap to faces of other objects
  };
  handles?: GizmoHandleOptions; // Per-handle visibility controls
};

GizmoHandleOptions

type AxisOptions = boolean | { x?: boolean; y?: boolean; z?: boolean };

type GizmoHandleOptions = {
  translate?: AxisOptions;      // Translate arrow handles (X, Y, Z)
  rotate?: AxisOptions;         // Rotate ring handles (RX, RY, RZ)
  scale?: AxisOptions;          // Scale cube handles (SX, SY, SZ)
  translatePlane?: AxisOptions; // Plane translate handles (TXY, TYZ, TZX) — requires advancedMode
  scalePlane?: AxisOptions;     // Plane scale handles (SXY, SYZ, SZX) — requires advancedMode
  center?: boolean;             // Center pivot handle
};

AxisOptions accepts:

• true / false — toggle all axes at once

• { x?: boolean, y?: boolean, z?: boolean } — per-axis control

Notes:

• Plane handles (TXY, TYZ, TZX, SXY, SYZ, SZX) are automatically hidden if either of their constituent axes is disabled. For example, disabling translate X also hides TXY and TZX.

• Plane handles additionally require advancedMode: true to be visible.

• Omitted groups are left unchanged from their current state.

GizmoState

type GizmoState = {
  enabled: boolean;
  advancedMode: boolean;
  localSpace: boolean;
  snap: {
    enabled: boolean;
    grid: boolean;
    angle: boolean;
    gridResolution: number;
    angleParam: number;
    toFace: boolean;
  };
  handles: {
    translate: { x: boolean; y: boolean; z: boolean };
    rotate: { x: boolean; y: boolean; z: boolean };
    scale: { x: boolean; y: boolean; z: boolean };
    translatePlane: { x: boolean; y: boolean; z: boolean };
    scalePlane: { x: boolean; y: boolean; z: boolean };
    center: boolean;
  };
};

Returns

Promise<GizmoState> - the full gizmo state after applying the options.

Examples

// Show the gizmo
await api.configureGizmo({ enabled: true });

// Hide the gizmo
await api.configureGizmo({ enabled: false });

// Enable advanced mode with local space orientation
await api.configureGizmo({ advancedMode: true, localSpace: true });

// Configure snapping
await api.configureGizmo({
  snap: {
    enabled: true,
    grid: true,
    gridResolution: 0.5,
    angle: true,
    angleParam: 15,
    toFace: true,
  },
});

// Restrict to X/Y plane translation only (no rotation, scale, or Z axis)
await api.configureGizmo({
  enabled: true,
  handles: {
    translate: { x: true, y: true, z: false },
    rotate: false,
    scale: false,
    translatePlane: false,
    scalePlane: false,
    center: false,
  },
});

// Disable only the Z rotation handle
await api.configureGizmo({
  handles: { rotate: { z: false } },
});

// Re-enable all handles
await api.configureGizmo({
  handles: {
    translate: true,
    rotate: true,
    scale: true,
    translatePlane: true,
    scalePlane: true,
    center: true,
  },
});