Batch Design Updates

When you need to apply multiple design changes at once — adding several elements, repositioning objects, or building complex layouts — you can group them into a single atomic batch. This ensures the canvas updates once with the final result, avoiding partial or inconsistent intermediate states.

Creating a Batch

Call kittl.createBatch() to get a batch object. It exposes the same API surface as kittl.design, so there are no new methods to learn.

const batch = await kittl.createBatch();

Queuing Operations

Use the batch object exactly like kittl.design. Operations are queued on the host until you commit.

const batch = await kittl.createBatch();

// Queue a shape
await batch.shape.createPredefinedShape({
  shapeType: 'circle',
  position: { absolute: { left: 100, top: 100 } },
  size: { width: 200, height: 200 },
});

// Queue text
await batch.text.addText({
  text: 'Hello',
  position: { absolute: { left: 350, top: 100 } },
  size: { width: 300, height: 60 },
});

// Queue a property update
await batch.object.updateProperties('obj-1', { left: 100 });

// Apply all changes at once
await batch.commit();

Key Behaviour

• Atomic application — all queued operations are applied together when commit() is called. The canvas updates once with the final result.
• Same API surface — the batch object mirrors kittl.design (shape, text, object, image, board, etc.), so existing code can be moved into a batch with minimal changes.
• Single-use — a batch is consumed after commit(). Calling commit() again on the same batch throws an error. Create a new batch for the next set of operations.

Multiple Independent Batches

You can create as many batches as you need. Each operates on its own queue and can be committed separately.

const batch1 = await kittl.createBatch();
const batch2 = await kittl.createBatch();

await batch1.shape.createPredefinedShape({
  shapeType: 'circle',
  position: { absolute: { left: 50, top: 50 } },
  size: { width: 100, height: 100 },
});

await batch2.text.addText({
  text: 'Independent text',
  position: { absolute: { left: 200, top: 200 } },
  size: { width: 300, height: 60 },
});

await batch1.commit(); // applies batch1 changes
await batch2.commit(); // applies batch2 changes

await batch1.commit(); // ❌ throws — batch already committed

When to Use Batches

Scenario	Without batch	With batch
Add 5 shapes to a board	Each shape appears one by one	All shapes appear together
Reposition multiple objects	Layout shifts between calls	All moves applied at once
Build a complex template	Partial states visible to the user	Final result appears instantly

tip

If you are only making a single design call, a batch is unnecessary — call kittl.design.* directly.