Adding Illustrations

Illustrations function similarly to standard images but are handled separately by the Kittl SDK, enabling support for features like SVG-specific adjustments.

Adding an Illustration Directly

You can insert an illustration using kittl.design.illustration.addIllustration by pointing to its source URL.

const addResult = await kittl.design.illustration.addIllustration({
    src: 'https://example.com/vector-art.svg',
    size: {
        width: 200,
        height: 200
    },
    position: {
        absolute: {
            left: 150,
            top: 150,
        },
    },
});

if (addResult.isOk) {
    console.log('Illustration added:', addResult.result);
}

Illustrations via Upload

To handle user-uploaded vector files, use the upload API first, then pass the resulting object reference to addIllustration.

// 1. Upload the SVG blob
const uploadResult = await kittl.upload.image.upload({ blob: svgBlob });

if (uploadResult.isOk && uploadResult.result.length > 0) {
    const uploadedVector = uploadResult.result[0];

    // 2. Add as an illustration
    const addResult = await kittl.design.illustration.addIllustration({
        src: uploadedVector.objectName,
        size: {
            width: 500,
            height: 500
        },
        position: {
            absolute: {
                left: 0,
                top: 0,
            },
        },
    });

    if (addResult.isOk) {
        console.log('Uploaded illustration placed on board.');
    }
}

Editing Illustration Paths

Use getPaths() to read an illustration's children. The path methods let you rename, hide, lock, or remove individual paths without replacing the whole illustration.

const paths = await kittl.design.illustration.getPaths({ id: 'illustration-id' });
if (paths.isOk) {
    console.log('Illustration paths:', paths.result);
}

await kittl.design.illustration.renamePath({
    illustrationId: 'illustration-id',
    pathId: 'path-id',
    newName: 'Outline',
});

await kittl.design.illustration.togglePathLocked({
    illustrationId: 'illustration-id',
    pathId: 'path-id',
    locked: true,
});

togglePathHidden() takes hidden instead of locked. removePaths() takes illustrationId and a pathIds array. See the published illustration API for signatures and result types.

Updating an Illustration

kittl.design.illustration.updateIllustration() accepts a required id and optional position, dimensions, source, fill, stroke, and shadow fields. For example:

await kittl.design.illustration.updateIllustration({
    id: 'illustration-id',
    left: 200,
    top: 150,
});

See UpdateIllustrationParams for every supported field.

Hiding and Removing Paths

kittl.design.illustration.togglePathHidden() takes the required illustrationId, pathId, and hidden fields:

await kittl.design.illustration.togglePathHidden({
    illustrationId: 'illustration-id',
    pathId: 'path-id',
    hidden: true,
});

kittl.design.illustration.removePaths() takes illustrationId and a pathIds: string[] array. Both methods were added in SDK 0.0.9. See ToggleHideIllustrationPathParams and RemoveIllustrationPathParams.