Drag and Drop

The kittl.dragAndDrop API lets you implement drag-and-drop from your extension panel into the Kittl canvas. It handles coordinate translation, native drag previews, and optional image persistence automatically.

Starting a Drag

Call startDragImageEvent inside a dragstart handler to set up the native drag preview and attach the drop logic. When the user releases over the canvas, the image is placed at the correct position.

const img = document.querySelector('img');

img.addEventListener('dragstart', (event) => {
    kittl.dragAndDrop.startDragImageEvent({
        event,
        img,
        persistImage: true, // upload & persist the image after drop
    });
});

See Drag and Drop API Reference for full parameter details.

Dropping an Image Programmatically

For advanced use cases, call dropImage directly to insert an image at specific coordinates without a native drag gesture.

const objectId = await kittl.dragAndDrop.dropImage({
    x: 400,
    y: 300,
    src: 'https://example.com/photo.jpg',
    imgWidth: 200,
    imgHeight: 150,
    persistImage: true,
});

if (objectId) {
    console.log('Dropped image:', objectId);
}

See Drag and Drop API Reference for full parameter details.

Return Value

Returns Promise<string | null> — the ID of the inserted object, or null if the drop failed.

tip

startDragImageEvent is the recommended approach for most use cases. It handles native drag previews, coordinate translation, and the full drop lifecycle automatically. Use dropImage only when you need programmatic control over the drop.