# configureGizmo

#### configureGizmo

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

#### Signature

```
configureGizmo(options: GizmoOptions): Promise<GizmoState>
```

#### Parameters

<table><thead><tr><th width="177.44140625">Parameter</th><th>Type</th><th width="106.859375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>GizmoOptions</code></td><td>Yes</td><td>Partial options to apply</td></tr></tbody></table>

#### GizmoOptions

```ts
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

```ts
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

```ts
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

```js
// 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,
  },
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.vectary.com/api/model-api/api-reference/configuregizmo.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.