Positioning System

Most design APIs that create or update elements accept a position parameter. The SDK supports three positioning strategies: absolute, relative, and screen-based.

Absolute Positioning

Place an element at exact pixel coordinates on the canvas, relative to the canvas origin.

position: {
    absolute: { left: 100, top: 50 },
}

Property	Type	Description
left	number	X offset from canvas origin (pixels)
top	number	Y offset from canvas origin (pixels)

Relative Positioning

Position an element relative to another element or the viewport.

Relative to Viewport

Center an element (or offset from center) within the current viewport.

// Center in viewport
position: {
    relative: { to: 'viewport', location: 'center' },
}

// Offset from viewport origin
position: {
    relative: { to: 'viewport', location: 'origin', offset: { left: 50, top: 50 } },
}

Relative to an Object

Position relative to another element's origin or center, with an optional offset.

// Center on another element
position: {
    relative: { to: 'element-id', location: 'center' },
}

// Offset from another element's origin (top-left)
position: {
    relative: { to: 'element-id', location: 'origin', offset: { left: 20, top: 30 } },
}

Relative to Screen

Position using screen coordinates, which are automatically transformed to canvas coordinates using the current viewport transform.

position: {
    relative: { to: 'screen', coordinates: { x: 400, y: 300 } },
}

// With an additional offset
position: {
    relative: { to: 'screen', coordinates: { x: 400, y: 300 }, offset: { left: 10, top: 10 } },
}

Type Reference

AbsolutePosition

{ absolute: { left: number; top: number } }

RelativePosition

One of the following:

Variant	to	Additional Properties
RelativeToViewport	'viewport'	location: 'origin' | 'center', offset?: { left, top }
RelativeToObject	Any element ID	location: 'origin' | 'center', offset?: { left, top }
RelativeToScreen	'screen'	coordinates: { x, y }, offset?: { left, top }

Dimensions

Used alongside position for sizing elements:

size: {
    width: 300,
    height: 200,
    applyViewportScale: true, // optional — scale relative to current zoom level
}

Property	Type	Description
width	number	Width in pixels
height	number	Height in pixels
applyViewportScale	boolean	If true, size adjusts based on the current zoom level

Smart Placement

kittl.design.placement.getSmartPlacement() computes placement rectangles for a group of objects. Pass each object's bounding box and optionally a target board, padding, or IDs to ignore when checking placement.

const placement = await kittl.design.placement.getSmartPlacement({
    objects: [{ left: 0, top: 0, width: 200, height: 100 }],
    padding: 16,
    targetBoardId: 'board-id',
});

if (placement.isOk) {
    console.log('Group bounds:', placement.result.insertionBoundingBox);
    console.log('Object positions:', placement.result.objectPlacements);
}

See SmartPlacementInput for all fields. This method computes positions; use the returned rectangles in your design operations.