Adding Shapes

Adding shapes is a fundamental step in building on the canvas. The Kittl SDK provides methods to add shapes depending on the desired structure and customization.

Predefined Shapes

Use createPredefinedShape to add common geometry such as rectangles, circles, stars, or polygons.

const circleResult = await kittl.design.shape.createPredefinedShape({
    shapeType: 'ellipse',
    size: {
        width: 200,
        height: 200
    },
    position: {
        absolute: {
            left: 100,
            top: 100,
        },
    },
});

if (circleResult.isOk) {
    console.log('Created circle:', circleResult.result);
}

Basic Shapes (Custom)

Use createBasicShape to define structural shapes with greater freedom, often used as structural placeholders or structural masks.

const basicShapeResult = await kittl.design.shape.createBasicShape({
    objectName: 'Custom Shape',
    size: {
        width: 300,
        height: 300
    },
    position: {
        absolute: {
            left: 50,
            top: 50,
        },
    },
});

if (basicShapeResult.isOk) {
    console.log('Created basic shape:', basicShapeResult.result);
}

Updating a Shape

Use updateShape to modify an existing shape's properties. The shape type cannot be changed — only visual properties, position, size, and styling.

// Update position and opacity
await kittl.design.shape.updateShape({
    id: 'shape-id',
    position: { absolute: { left: 150, top: 200 } },
    opacity: 0.75,
});

// Update fill using the fill array
await kittl.design.shape.updateShape({
    id: 'shape-id',
    fill: [
        { key: 'fill', value: '#00ff00', visible: true },
    ],
    strokeWidth: 2,
    stroke: '#000000',
});

// Or use fillColor as a shortcut for a single color
await kittl.design.shape.updateShape({
    id: 'shape-id',
    fillColor: '#00ff00',
});

// Resize and rotate
await kittl.design.shape.updateShape({
    id: 'shape-id',
    size: { width: 300, height: 200 },
    angle: 45,
});

See Shape API Reference for the full list of updatable properties.

Note: Basic shapes use a fill array of ColorInfo objects (supporting multiple fills, gradients, and visibility per entry). This differs from text elements, which use a single Color value. The fillColor shortcut lets you set a simple color without constructing the full array.

Rotating shapes

While updateShape supports angle for setting absolute rotation, you can also use kittl.design.object.rotateObject to rotate any object (including shapes) by a relative angle.

Converting a Shape to a Mask

Use convertShapeToMask to turn a basic shape into a mask group. The shape must be directly on a board (not already inside a group).

const maskGroup = await kittl.design.shape.convertShapeToMask({
    id: 'shape-id',
});

console.log('Created mask group:', maskGroup);