Layers: Content Elements on a Slide

A layer is a single flat object that describes one content element on a slide. You describe it with { type, ...fields, at }, where type selects the kind of content, the remaining fields configure that content, and at is the bounding box that places it on the canvas. There are ten layer types in total, covering text, lists, charts, tables, images, shapes, and icons. Every layer type is fully schema-validated, so your editor can autocomplete all valid fields and flag any invalid values at call time.

The geometry field: `at`

Every layer, regardless of type, requires an at field that positions it on the 1920 × 1080 slide canvas (or whatever size preset you’ve chosen). All coordinates and dimensions are in pixels.

at: {
  x: 160,        // distance from the left edge
  y: 120,        // distance from the top edge
  w: 1600,       // width
  h: 200,        // height
  rotation: 45,  // optional: rotation in degrees (default 0)
}

Optional common fields

Beyond at, every layer type also accepts these optional fields:

Field	Type	Purpose
`z`	`number` (integer)	Stacking order — higher values appear in front
`prompt`	`string`	AI brief: plain-language instruction for what the AI should generate in this slot
`examples`	`string[]`	Sample outputs that guide AI generation for this layer
`effects`	`object`	Visual effects — opacity, corner radius, drop shadows, filters

{
  type: 'text',
  text: 'Key Metric',
  style: 'h2',
  at: { x: 160, y: 120, w: 800, h: 120 },
  z: 10,
  prompt: 'A bold heading that highlights the most important number on this slide',
}

All ten layer types

text

Display text, headings, and body copy. Supports all eight theme text styles.

bullets

Unordered bulleted list. Accepts bullet marker styling — icon, color, size, spacing.

numbered

Ordered (numbered) list. Supports decimal, alpha, and roman numeral markers.

bar

Bar or horizontal-bar chart shorthand. Pass data: [{ label, value }] and you’re done.

donut

Donut (ring) chart shorthand. Best for part-to-whole comparisons.

chart

Full chart structure — every family and feature via document.

table

Data table with columns, rows, header styling, alternating rows, and borders.

image

Image from a public HTTPS URL. Compiled to a rectangle shape with imageFill.

shape

Vector shape: rectangle, circle, ellipse, triangle, or line.

icon

Named icon from the Ablo icon library, referenced by key string.

Layer type reference

`text` — styled text block

Renders a block of text. The style field maps to one of eight theme-controlled text styles, but you can override individual properties like fontSize, color, fontFamily, or bold inline.

{
  type: 'text',
  text: 'Revenue grew 40% YoY',
  style: 'h1',                    // 'title' | 'h1' | 'h2' | 'h3' | 'body1' | 'body2' | 'note' | 'caption'
  color: '#5B4CF5',               // optional override
  bold: true,                     // optional override
  align: 'center',                // 'left' | 'center' | 'right' | 'justify'
  at: { x: 160, y: 120, w: 1600, h: 160 },
}

Pass an array of strings to render multiple paragraphs:

{
  type: 'text',
  text: ['First paragraph', 'Second paragraph'],
  style: 'body1',
  at: { x: 160, y: 300, w: 1400, h: 400 },
}

`bullets` — bulleted list

Renders an unordered list. Pass items as an array of strings. Bullet marker style, color, size, and spacing are all configurable.

{
  type: 'bullets',
  items: ['Shipped v2 API', 'Onboarded 12 enterprise accounts', 'Reduced p99 latency by 60%'],
  style: 'body1',
  bulletStyle: 'circle-filled',   // optional icon key for the bullet marker
  bulletColor: '#5B4CF5',         // optional bullet color
  itemSpacing: 16,                // optional vertical gap between items (px)
  at: { x: 160, y: 200, w: 1400, h: 600 },
}

`numbered` — ordered list

Renders a numbered list. The listStyle field controls the marker format.

{
  type: 'numbered',
  items: ['Define the problem', 'Prototype a solution', 'Validate with users'],
  listStyle: 'decimal',           // 'decimal' | 'lower-alpha' | 'upper-alpha' | 'lower-roman' | 'upper-roman'
  at: { x: 160, y: 200, w: 1400, h: 600 },
}

`bar` — bar chart (shorthand)

The bar type is a shorthand for a vertical or horizontal bar chart. Pass data as an array of { label, value } objects.

{
  type: 'bar',
  data: [
    { label: 'Q1', value: 420 },
    { label: 'Q2', value: 610 },
    { label: 'Q3', value: 780 },
    { label: 'Q4', value: 940 },
  ],
  title: 'Quarterly Revenue ($k)',
  orientation: 'vertical',        // 'vertical' | 'horizontal'
  valueFormat: '$,.0f',
  dataLabels: true,
  at: { x: 160, y: 260, w: 1200, h: 680 },
}

`donut` — donut chart (shorthand)

The donut type is a shorthand for a donut (ring) chart. Like bar, it compiles to the full chart layer.

{
  type: 'donut',
  data: [
    { label: 'Enterprise', value: 62 },
    { label: 'Mid-Market', value: 28 },
    { label: 'SMB',        value: 10 },
  ],
  title: 'Revenue by Segment',
  valueFormat: '.0f',
  at: { x: 500, y: 200, w: 900, h: 700 },
}

`chart` — full chart structure

When you need a chart family beyond bar or donut — or you want full control over datasets, scales, axes, and affordances — use the chart type and supply a document object directly. Supported families include bar, stacked-bar, line, combo, pie, donut, waterfall, funnel, scatter, bubble, mekko, gantt, and range.

{
  type: 'chart',
  document: {
    family: 'waterfall',
    data: [
      { label: 'Starting ARR', value: 1200 },
      { label: 'New Logos',    value: 340  },
      { label: 'Expansion',   value: 210  },
      { label: 'Churn',       value: -180 },
      { label: 'Ending ARR',  value: 1570 },
    ],
  },
  at: { x: 160, y: 260, w: 1400, h: 680 },
}

`table` — data table

Renders a styled data table. Columns can carry alignment, width, and per-column style. Cells can be plain strings/numbers, or rich objects with colSpan, rowSpan, and custom styling. The styles field controls header appearance, alternating row colors, and border presets.

{
  type: 'table',
  columns: [
    { header: 'Region',  align: 'left', width: 300 },
    { header: 'Revenue', align: 'right' },
    { header: 'Growth',  align: 'right' },
  ],
  rows: [
    ['Americas', '$4.2M', '+18%'],
    ['EMEA',     '$2.8M', '+31%'],
    ['APAC',     '$1.1M', '+47%'],
  ],
  headerRows: 1,
  at: { x: 160, y: 200, w: 1600, h: 620 },
}

`image` — image from URL

Renders an image sourced from a public HTTPS URL. The image is automatically re-hosted to the Ablo CDN server-side. The image type is persisted as a shape layer carrying an image fill — there is no separate image layer type in the persistence model.

{
  type: 'image',
  url: 'https://cdn.example.com/product-screenshot.png',
  objectFit: 'contain',   // 'cover' | 'contain' | 'fill' (default: 'cover')
  at: { x: 960, y: 160, w: 820, h: 680 },
}

The image layer is persisted as a shape layer with an imageFill. The LayerResource.type returned after creation will be 'shape', not 'image'. This is expected — image is an authoring shorthand that the SDK maps to a rectangle shape with an image fill.

`shape` — vector shape

Renders a filled vector shape. Use fill for a hex color, gradient for a CSS gradient string, or the structured fills array for advanced multi-stop fills. Rectangles support a radius for rounded corners. The line shape supports endpoint coordinates (x1, y1, x2, y2) and optional arrowheads.

// Rounded rectangle
{
  type: 'shape',
  shape: 'rectangle',             // 'rectangle' | 'circle' | 'ellipse' | 'triangle' | 'line'
  fill: '#5B4CF5',
  radius: 12,
  opacity: 0.9,
  at: { x: 160, y: 120, w: 400, h: 400 },
}

// Arrow line
{
  type: 'shape',
  shape: 'line',
  stroke: '#333333',
  strokeWidth: 3,
  arrowEnd: true,
  at: { x: 400, y: 540, w: 600, h: 1 },
}

`icon` — named icon

Renders a named icon from the Ablo icon library. Pass the icon key as a string, plus an optional color.

{
  type: 'icon',
  icon: 'rocket',                 // icon key from the Ablo icon library
  color: '#5B4CF5',
  at: { x: 880, y: 440, w: 160, h: 160 },
}

Shorthand types vs. persisted types

Two of the ten authoring types compile to a different persisted type. This is transparent in use — you write the friendly authoring type and the SDK handles the translation.

Authoring type	Persisted as	Notes
`bar`	`chart`	Bar chart shorthand — pass `data: [{ label, value }]`
`donut`	`chart`	Donut chart shorthand — pass `data: [{ label, value }]`
`image`	`shape`	Rectangle shape carrying an image fill

When you call ablo.layers.create() or read back a layer via ablo.layers.retrieve(), the type field reflects the persisted type, not the authoring shorthand.

Get Started

Core Concepts

Layers

Styling

Guides

Layers: Content Elements on a Slide

The geometry field: `at`

Optional common fields

All ten layer types

text

bullets

numbered

bar

donut

chart

table

image

shape

icon

Layer type reference

`text` — styled text block

`bullets` — bulleted list

`numbered` — ordered list

`bar` — bar chart (shorthand)

`donut` — donut chart (shorthand)

`chart` — full chart structure

`table` — data table

`image` — image from URL

`shape` — vector shape

`icon` — named icon

Shorthand types vs. persisted types

​The geometry field: at

​Optional common fields

​All ten layer types

text

bullets

numbered

bar

donut

chart

table

image

shape

icon

​Layer type reference

​text — styled text block

​bullets — bulleted list

​numbered — ordered list

​bar — bar chart (shorthand)

​donut — donut chart (shorthand)

​chart — full chart structure

​table — data table

​image — image from URL

​shape — vector shape

​icon — named icon

​Shorthand types vs. persisted types

The geometry field: `at`

Optional common fields

All ten layer types

Layer type reference

`text` — styled text block

`bullets` — bulleted list

`numbered` — ordered list

`bar` — bar chart (shorthand)

`donut` — donut chart (shorthand)

`chart` — full chart structure

`table` — data table

`image` — image from URL

`shape` — vector shape

`icon` — named icon

Shorthand types vs. persisted types