> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryablo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Layers: Content Elements on a Slide
> Explore all ten layer types available in the Ablo Decks SDK — from text and charts to shapes and icons — and learn how to position and stack them.
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.
```typescript theme={null}
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 |
```typescript theme={null}
{
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
Display text, headings, and body copy. Supports all eight theme text styles.
Unordered bulleted list. Accepts bullet marker styling — icon, color, size, spacing.
Ordered (numbered) list. Supports decimal, alpha, and roman numeral markers.
Bar or horizontal-bar chart shorthand. Pass `data: [{ label, value }]` and you're done.
Donut (ring) chart shorthand. Best for part-to-whole comparisons.
Full chart structure — every family and feature via `document`.
Data table with columns, rows, header styling, alternating rows, and borders.
Image from a public HTTPS URL. Compiled to a rectangle shape with `imageFill`.
Vector shape: `rectangle`, `circle`, `ellipse`, `triangle`, or `line`.
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.
```typescript theme={null}
{
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:
```typescript theme={null}
{
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.
```typescript theme={null}
{
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.
```typescript theme={null}
{
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.
```typescript theme={null}
{
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.
```typescript theme={null}
{
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`.
```typescript theme={null}
{
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.
```typescript theme={null}
{
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.
```typescript theme={null}
{
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.
```typescript theme={null}
// 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`.
```typescript theme={null}
{
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.