sdk.shapeapi.updateshape

Home > @kittl/sdk > ShapeAPI > updateShape

ShapeAPI.updateShape() method

Updates an existing basic shape object with new properties.

This method modifies the properties of an existing shape while preserving its identity and type. You can update visual properties, position, size, and styling without recreating the entire shape. The shape type itself cannot be changed - use delete and create operations for type changes.

**Updatable Properties:** - Position (absolute coordinates or relative positioning) - Size (with automatic scale recalculation) - Visual styling (opacity, rotation, skew, flips) - Fill color and patterns - Border properties (stroke width, color, style) - Shadow effects - Custom naming

**Position Updates:** - Absolute positioning moves the shape to exact pixel coordinates - Relative positioning can reposition relative to other elements - Position changes respect artboard boundaries and constraints

**Size Updates:** - Size changes automatically recalculate scale factors based on shape's default dimensions - Maintains aspect ratio unless both width and height are explicitly provided - Viewport scaling applies when applyViewportScale is enabled

Signature:

updateShape(input: UpdateShapeInput, opts?: DesignApiOptions): NormalizedBasicShapeObject;

Parameters

Parameter	Type	Description
input	UpdateShapeInput	Shape update configuration
opts	DesignApiOptions	(Optional) Optional execution configuration controlling patch behavior and change tracking

Returns:

NormalizedBasicShapeObject

The updated NormalizedBasicShapeObject with all applied changes

Exceptions

When shape with specified ID is not found

When target object is not a basic shape type

When unable to determine shape type from object name

When position calculation fails

When size constraints are violated

Example

// Update shape position and opacity
const updated = api.updateShape({
  id: 'shape-123',
  position: { absolute: { left: 150, top: 200 } },
  opacity: 0.75
});

// Update border styling
api.updateShape({
  id: 'shape-123',
  border: {
    strokeWidth: 5,
    stroke: '#ff0000'
  }
});

// Resize and rotate
api.updateShape({
  id: 'shape-123',
  size: { width: 300, height: 200, applyViewportScale: false },
  angle: 45
});

// Batch multiple updates for performance
const batchClient = designController.createBatchClient();
api.updateShape({ id: 'shape-1', fillColor: '#00ff00' }, { batchClient });
api.updateShape({ id: 'shape-2', opacity: 0.5 }, { batchClient });
batchClient.commit();