The ablo.layers namespace manages the individual content elements — text, charts, tables, images, shapes, and icons — that live on a slide. Layers are addressed by id; capture the id returned by create and pass it directly to update, applyOp, or delete without an intermediate lookup. For read-modify-write edits to chart, table, or text content, use applyOp rather than update — it applies a typed operation against the current stored content so only the targeted fields change.
ablo.layers.create(slideId, layer, options?)Adds a single layer to a slide. The layer argument is a flat, discriminated-union object; the SDK validates and compiles it before committing.
Parameters The id of the slide to add the layer to.
A flat object describing the layer to create. The type field discriminates the union. Common fields shared by all layer types: Show Shared fields (all types)
Layer type. One of "text", "bullets", "numbered", "bar", "donut", "chart", "table", "image", "shape", "icon".
at
{ x, y, w, h, rotation? }
required
Position and size in the 1920×1080 slide coordinate space.
Z-index integer. Higher values appear in front.
Visual effects: opacity, corner radius, CSS filter, vertical alignment, drop shadows.
AI brief — a plain-language instruction for what the AI should generate in this slot.
Sample outputs that guide AI generation for this slot.
text
string | string[]
required
Text content. Pass an array for multi-paragraph text.
style
'title' | 'h1' | 'h2' | 'h3' | 'body1' | 'body2' | 'note' | 'caption'
Theme text style. CSS variables from the applied theme resolve the visual appearance.
Explicit font size in points.
align
'left' | 'center' | 'right'
Horizontal text alignment.
Show type: 'bar' | 'donut'
data
Array<{ label: string; value: number }>
required
Chart data series. At least one datum is required.
orientation
'vertical' | 'horizontal'
Bar chart orientation (bar only).
D3-style format string for axis/label values.
Show data labels on bars/segments.
Overlay a CAGR arrow annotation (bar only).
document
CreateChartDocumentInput
required
Full chart structure for any chart family. Validated by createChartDocument() against the canonical ChartDocumentSchema.
columns
string[] | ColumnDef[]
required
Column headers. Pass strings for simple headers or ColumnDef objects for typed columns with widths and styles.
Table rows, each an array of cells matching the column count.
Number of leading rows to treat as header rows. Defaults to 1.
Absolute URL of the image. Supported MIME types: image/jpeg, image/png, image/gif, image/webp, image/svg+xml, image/avif.
objectFit
'cover' | 'contain' | 'fill'
How the image fills its bounding box.
wait
'queued' | 'confirmed'
default: "confirmed"
'confirmed' (default) waits for the durable acknowledgement. 'queued' returns as soon as the server accepts the write.
Idempotency key for safe retries.
Returns Client-minted UUID for the new layer.
The layer type, e.g. "text", "bar", "table".
Example import { Decks } from '@abloatai/decks' ; const ablo = new Decks ( process . env . ABLO_API_KEY ! ); const layer = await ablo . layers . create ( 'slide_xyz789' , { type: 'bar' , data: [ { label: 'Q1' , value: 120 }, { label: 'Q2' , value: 180 }, { label: 'Q3' , value: 252 }, ], orientation: 'vertical' , at: { x: 160 , y: 300 , w: 900 , h: 600 }, }); console . log ( layer . id ); // save this to update the chart data later
ablo.layers.createRaw(params, options?)Advanced escape hatch for creating a layer from raw CreateLayerParams. Use this when you need to supply a fully-constructed data or contentJson payload that the higher-level LayerInput builders do not expose.
Parameters params
CreateLayerParams
required
type
'text' | 'shape' | 'icon' | 'path' | 'table' | 'chart'
required
The layer type.
Geometry in the slide coordinate space: { x, y, width, height, rotation? }.
Lock the layer against accidental edits in the editor.
Plain-text shorthand for text layers. The SDK converts this to the layer’s rich text representation. Ignored when contentJson is also present.
Rich content document for text-bearing layers. When provided, takes precedence over text.
Type-specific payload: { chartDocument } for charts, TableData for tables, { shapeType, ... } for shapes.
Layer-level style overrides.
Picture fill for shape layers: { url, objectFit?, width?, height? }.
wait
'queued' | 'confirmed'
default: "confirmed"
Acknowledgement level to wait for.
Idempotency key for safe retries.
Returns Client-minted UUID for the new layer.
Example const layer = await ablo . layers . createRaw ({ slideId: 'slide_xyz789' , type: 'text' , position: { x: 160 , y: 120 , width: 1600 , height: 160 }, contentJson: myPrebuiltContentDoc , }); console . log ( layer . id );
ablo.layers.retrieve(id)Fetches the full stored record for a layer by id. Requires a readable client.
Parameters Returns Geometry: { x, y, width, height, rotation? } in the 1920×1080 coordinate space.
Type-specific payload (chart document, table data, shape descriptor).
Rich text content for text-bearing layers. null for non-text types.
style
Record<string, unknown> | null
Layer-level style overrides.
Whether the layer is visible.
The layout layer this slide layer is bound to, or null for free layers.
Example const layer = await ablo . layers . retrieve ( 'layer_def456' ); console . log ( layer . type , layer . position );
ablo.layers.list({ slideId })Returns all layers on a slide. Requires a readable client.
Parameters The slide whose layers you want to list.
Returns An array of LayerRecord objects. Each entry has the same shape as the return value of retrieve.
Example const layers = await ablo . layers . list ({ slideId: 'slide_xyz789' }); for ( const layer of layers ) { console . log ( layer . zIndex , layer . type , layer . position ); }
ablo.layers.update(params, options?)Applies a field-level patch to an existing layer. Each field you include overwrites the entire stored value for that field; fields you omit are left unchanged. Use applyOp instead when you want to surgically modify chart series, table cells, or text styles.
Parameters params
UpdateLayerParams
required
Geometry patch. Provide only the sub-fields you want to change (x, y, width, height, rotation).
Lock or unlock the layer in the editor.
Replacement rich text content for text-bearing layers. Overwrites the entire stored content.
Replacement type-specific payload. Overwrites the entire data object.
Replacement style overrides. Overwrites the entire style object.
Replacement picture fill: { url, attachmentId?, objectFit?, width?, height? }.
metadata
LayerCompositionMetadata | null
AI brief and placeholder metadata. Pass null to clear. Contains prompt, examples, and placeholder slot fields used by the Ablo generation pipeline.
wait
'queued' | 'confirmed'
default: "confirmed"
Acknowledgement level to wait for.
Idempotency key for safe retries.
Returns The acknowledgement level reached.
Monotonic sync cursor for real-time clients.
Example // Move a layer and hide it in one commit const receipt = await ablo . layers . update ({ id: 'layer_def456' , position: { x: 320 , y: 200 }, visible: false , }); console . log ( receipt . status ); // 'confirmed'
ablo.layers.applyOp(id, op, options?)Applies a typed operation to a chart, table, or text layer using a read-modify-write cycle. The SDK reads the layer’s current document from the server, applies the op through the same reducers used by the editor and the AI, and writes only the changed fields back — so unrelated parts of the document are never overwritten.
This method requires a readable client. If your client is commit-only, it throws with a clear error.
Parameters A typed operation. The op type must match the layer type: Show ChartOp — for chart layers
A ChartOperation from the charts toolkit. Examples: add or remove a series, change chart type, update axis labels, set a color palette.
Show TableOp — for table layers
A TableOperation from the tables toolkit. Examples: set a cell value, add or remove a row/column, apply cell styles, merge cells.
Show TextOp — for text layers
A TextStyleOperation from the text-style toolkit. Examples: change font size, toggle bold, update text color, set alignment.
wait
'queued' | 'confirmed'
default: "confirmed"
Acknowledgement level to wait for.
Idempotency key for safe retries.
Returns The acknowledgement level reached.
Monotonic sync cursor for real-time clients.
Example // On first run, create the deck and capture the layer id const deck = await ablo . decks . create ({ title: 'Live Dashboard' , slides: [ { title: 'Revenue' , layers: [ { type: 'table' , columns: [ 'Quarter' , 'Revenue' ], rows: [[ 'Q1' , '$1.2M' ]], at: { x: 160 , y: 300 , w: 1200 , h: 400 }, }, ], }, ], }); const tableLayerId = deck . slides [ 0 ]. layers [ 0 ]. id ; // On subsequent runs, apply a typed op to add a row — no full rewrite needed const receipt = await ablo . layers . applyOp ( tableLayerId , { type: 'insertRow' , index: 1 , cells: [{ value: 'Q2' }, { value: '$1.5M' }], }); console . log ( receipt . status ); // 'confirmed'
ablo.layers.delete(id, options?)Permanently deletes a layer from its slide.
Parameters wait
'queued' | 'confirmed'
default: "confirmed"
Acknowledgement level to wait for.
Idempotency key for safe retries.
Returns The acknowledgement level reached.
Example const receipt = await ablo . layers . delete ( 'layer_def456' ); console . log ( receipt . status ); // 'confirmed'