> ## 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.

# LayerInput — Complete Flat Layer Types Reference

> Complete reference for the LayerInput discriminated union — the flat, one-object API for describing every layer type in a slide.

`LayerInput` is the flat, one-object authoring format for all ten layer types. Every place in the SDK that accepts a layer — `decks.create`, `slides.create`, `layers.create`, and `layouts.create` — accepts a `LayerInput`. The object is discriminated on `type`: set `type` to the kind of content you want and add the matching fields alongside the required `at` geometry.

The compiler validates your input through Zod, maps friendly input types (`'bar'`, `'donut'`) to their stored representation (`'chart'`), and builds canonical structured documents for text, charts, and tables — you never write those by hand.

***

## Common fields

Every layer type shares these fields.

<ParamField path="at" type="At" required>
  Layer geometry in 1920×1080 slide coordinates.

  <Expandable title="At fields">
    <ParamField path="x" type="number" required>Left edge of the layer box in pixels.</ParamField>
    <ParamField path="y" type="number" required>Top edge in pixels.</ParamField>
    <ParamField path="w" type="number" required>Width in pixels. Must be positive.</ParamField>
    <ParamField path="h" type="number" required>Height in pixels. Must be positive.</ParamField>
    <ParamField path="rotation" type="number">Clockwise rotation in degrees around the layer's center.</ParamField>
  </Expandable>
</ParamField>

<ParamField path="z" type="number">
  Integer stacking order (z-index). Higher values render on top of lower values. When omitted, the server assigns a value based on insertion order.
</ParamField>

<ParamField path="prompt" type="string">
  AI brief — a plain-language instruction for what the AI should generate for this layer. Stored in layer metadata and read by Ablo's generation pipeline.
</ParamField>

<ParamField path="examples" type="string[]">
  Sample outputs that guide AI generation for this layer. Each string is one example of the content you expect.
</ParamField>

<ParamField path="effects" type="EffectsInput">
  Visual effects applied to the layer box: opacity, corner radius, blur, vertical alignment, and drop shadows.
</ParamField>

***

## `type: 'text'`

A text layer. The `text` field accepts a single string or an array of strings (each string becomes a paragraph).

<ParamField path="type" type="&#x22;text&#x22;" required />

<ParamField path="text" type="string | string[]" required>The content. An array of strings produces multiple paragraphs.</ParamField>

<Expandable title="Text styling fields">
  <ParamField path="style" type="TextStyle">
    Theme text style preset: `'title'` | `'h1'` | `'h2'` | `'h3'` | `'body1'` | `'body2'` | `'note'` | `'caption'`. Applies the theme's size, weight, and spacing for that style level.
  </ParamField>

  <ParamField path="fontSize" type="string">Font size, e.g. `'32px'` or `'2rem'`. Overrides the style preset size.</ParamField>
  <ParamField path="color" type="string">Text color. Accepts any CSS color or a `var(--slide-*)` token reference.</ParamField>
  <ParamField path="fontFamily" type="FontFamily">Font family — must be one of the supported families.</ParamField>
  <ParamField path="fontWeight" type="FontWeight">Font weight on the 100–900 axis, e.g. `'400'`, `'700'`.</ParamField>
  <ParamField path="lineHeight" type="string">Line height, e.g. `'1.5'`.</ParamField>
  <ParamField path="letterSpacing" type="string">Letter spacing (tracking), e.g. `'0.02em'`.</ParamField>
  <ParamField path="backgroundColor" type="string">Inline text highlight color.</ParamField>
  <ParamField path="spaceBefore" type="string">Paragraph spacing above, e.g. `'12px'`.</ParamField>
  <ParamField path="spaceAfter" type="string">Paragraph spacing below.</ParamField>
  <ParamField path="bold" type="boolean">Apply bold weight.</ParamField>
  <ParamField path="italic" type="boolean">Apply italic style.</ParamField>
  <ParamField path="align" type="'left' | 'center' | 'right' | 'justify'">Text alignment.</ParamField>
</Expandable>

```typescript theme={null}
{ type: 'text', text: 'Revenue up 40%', style: 'h1', at: { x: 160, y: 80, w: 1200, h: 120 } }

{ type: 'text', text: ['First paragraph.', 'Second paragraph.'], style: 'body1',
  at: { x: 160, y: 240, w: 800, h: 400 } }
```

***

## `type: 'bullets'`

A bullet list. Each string in `items` becomes one bullet point.

<ParamField path="type" type="&#x22;bullets&#x22;" required />

<ParamField path="items" type="string[]" required>List items. Must contain at least one item.</ParamField>

<Expandable title="Bullet styling fields">
  All [text styling fields](#type-text) plus:
  <ParamField path="listStyleType" type="'disc' | 'circle' | 'square'">Standard CSS bullet marker shape.</ParamField>
  <ParamField path="bulletStyle" type="string">Custom icon key for the bullet marker, e.g. `'arrow-right'`, `'circle-filled'`.</ParamField>
  <ParamField path="bulletColor" type="string">Color of the bullet marker (independent of text color).</ParamField>
  <ParamField path="bulletSize" type="number">Bullet marker size in pixels.</ParamField>
  <ParamField path="bulletStrokeWidth" type="number">Stroke width for outline-style bullet icons.</ParamField>
  <ParamField path="itemSpacing" type="number">Vertical spacing between list items in pixels.</ParamField>
  <ParamField path="bulletTextGap" type="number">Horizontal gap between the bullet marker and the text.</ParamField>
  <ParamField path="bulletAlign" type="'center' | 'top'">Vertical alignment of the bullet relative to its text line.</ParamField>
</Expandable>

```typescript theme={null}
{ type: 'bullets', items: ['ARR $4.2M', 'NRR 118%', '240 customers'],
  style: 'body1', bulletColor: 'var(--slide-brand)',
  at: { x: 160, y: 240, w: 700, h: 500 } }
```

***

## `type: 'numbered'`

A numbered list. Each string in `items` becomes one numbered item.

<ParamField path="type" type="&#x22;numbered&#x22;" required />

<ParamField path="items" type="string[]" required>List items. Must contain at least one item.</ParamField>

<Expandable title="Numbered list styling fields">
  All [text styling fields](#type-text) plus:
  <ParamField path="listStyle" type="'decimal' | 'lower-alpha' | 'upper-alpha' | 'lower-roman' | 'upper-roman'">Marker style. Default is `'decimal'` (1, 2, 3…).</ParamField>
  <ParamField path="listColor" type="string">Color of the number markers.</ParamField>
  <ParamField path="listSize" type="number">Marker font size in pixels.</ParamField>
  <ParamField path="listFontFamily" type="string">Font family for the markers (independent of text).</ParamField>
  <ParamField path="listFontWeight" type="string">Font weight for the markers.</ParamField>
  <ParamField path="itemSpacing" type="number">Vertical spacing between items in pixels.</ParamField>
  <ParamField path="listTextGap" type="number">Gap between the marker and the item text.</ParamField>
  <ParamField path="listAlign" type="'center' | 'top'">Vertical alignment of the marker relative to its text line.</ParamField>
</Expandable>

```typescript theme={null}
{ type: 'numbered', items: ['Define the problem', 'Identify stakeholders', 'Draft solution'],
  style: 'body1', listStyle: 'decimal',
  at: { x: 160, y: 240, w: 800, h: 500 } }
```

***

## `type: 'bar'`

A bar chart (vertical or horizontal). The SDK compiles this into a full `ChartDocument` and stores it as a `'chart'` layer.

<ParamField path="type" type="&#x22;bar&#x22;" required />

<ParamField path="data" type="ChartDatum[]" required>
  Chart data. Each datum has `label` (string), `value` (number), and an optional `color` override.

  <Expandable title="ChartDatum fields">
    <ParamField path="label" type="string" required>Bar label.</ParamField>
    <ParamField path="value" type="number" required>Bar value.</ParamField>
    <ParamField path="color" type="string">Per-bar color override.</ParamField>
    <ParamField path="id" type="string">Stable id for the datum — used for incremental updates.</ParamField>
  </Expandable>
</ParamField>

<ParamField path="title" type="string">Optional chart title rendered above the chart.</ParamField>
<ParamField path="orientation" type="'vertical' | 'horizontal'">Bar direction. Default is `'vertical'`.</ParamField>
<ParamField path="valueFormat" type="string">D3-style number format string, e.g. `'$0.0"M"'`, `'0,0'`, `'0%'`.</ParamField>
<ParamField path="dataLabels" type="boolean">Show value labels on each bar.</ParamField>
<ParamField path="cagrArrow" type="boolean">Render a CAGR arrow between the first and last bar.</ParamField>

```typescript theme={null}
{ type: 'bar',
  data: [
    { label: 'Q1', value: 2.1 },
    { label: 'Q2', value: 2.8 },
    { label: 'Q3', value: 3.4 },
  ],
  valueFormat: '$0.0"M"',
  dataLabels: true,
  cagrArrow: true,
  at: { x: 160, y: 240, w: 900, h: 620 } }
```

***

## `type: 'donut'`

A donut chart. Compiles to a `'chart'` layer.

<ParamField path="type" type="&#x22;donut&#x22;" required />

<ParamField path="data" type="ChartDatum[]" required>Slice data — same shape as bar chart data.</ParamField>
<ParamField path="title" type="string">Optional center label.</ParamField>
<ParamField path="valueFormat" type="string">Number format string for slice labels.</ParamField>
<ParamField path="dataLabels" type="boolean">Show labels on each slice.</ParamField>

```typescript theme={null}
{ type: 'donut',
  data: [
    { label: 'Enterprise', value: 62, color: '#3B82F6' },
    { label: 'Mid-Market', value: 28, color: '#60A5FA' },
    { label: 'SMB',        value: 10, color: '#BAE6FD' },
  ],
  valueFormat: '0%',
  at: { x: 600, y: 240, w: 720, h: 600 } }
```

***

## `type: 'chart'`

The full chart API — every chart family (bar, stacked bar, line, combo, pie, donut, waterfall, funnel, scatter, bubble, mekko, gantt, range) with full control over datasets, marks, encodings, scales, axes, legend, and affordances. Pass a `CreateChartDocumentInput` — the same input the Ablo chart toolkit accepts.

<ParamField path="type" type="&#x22;chart&#x22;" required />

<ParamField path="document" type="CreateChartDocumentInput" required>
  The full chart structure. Validated against the `ChartDocumentSchema` at compile time; family-default affordances are filled in automatically.
</ParamField>

Use `type: 'bar'` and `type: 'donut'` for the common cases. Use `type: 'chart'` when you need a chart family or configuration option those shortcuts don't expose.

***

## `type: 'table'`

A data table. Columns can carry alignment, width, and per-column style; cells can be plain values or rich objects with colspan/rowspan.

<ParamField path="type" type="&#x22;table&#x22;" required />

<ParamField path="columns" type="(string | ColumnDef)[]" required>
  Column definitions. Pass a bare string for a simple header, or an object with `{ header, key?, align?, verticalAlign?, width?, style? }` for full control. Column keys are auto-generated from headers if omitted.
</ParamField>

<ParamField path="rows" type="CellInput[][]" required>
  Row data. Each row is an array of cell values aligned to the columns. Cells can be a string, number, `null`, or a rich `{ text?, content?, align?, verticalAlign?, backgroundColor?, colSpan?, rowSpan? }` object.
</ParamField>

<ParamField path="headerRows" type="number">
  Number of header rows at the top (default 1). These rows receive the `styles.header` style.
</ParamField>

```typescript theme={null}
{ type: 'table',
  columns: ['Quarter', { header: 'Revenue', align: 'right' }, { header: 'Growth', align: 'right' }],
  rows: [
    ['Q1', '$2.1M', '+18%'],
    ['Q2', '$2.8M', '+33%'],
    ['Q3', '$3.4M', '+21%'],
  ],
  headerRows: 1,
  at: { x: 160, y: 200, w: 1100, h: 600 } }
```

***

## `type: 'image'`

An image layer. Stored internally as a `'shape'` layer with an `imageFill`. External URLs are automatically rehosted to the Ablo CDN at commit time. Use `ablo.images.upload()` for local files.

<ParamField path="type" type="&#x22;image&#x22;" required />

<ParamField path="url" type="string" required>A valid HTTPS URL. External URLs are rehosted to the Ablo CDN on commit.</ParamField>
<ParamField path="objectFit" type="'cover' | 'contain' | 'fill'">How the image fills its bounding box. Default is `'cover'`.</ParamField>
<ParamField path="width" type="number">Intrinsic width hint in pixels.</ParamField>
<ParamField path="height" type="number">Intrinsic height hint in pixels.</ParamField>

```typescript theme={null}
{ type: 'image',
  url: 'https://cdn.example.com/product-shot.jpg',
  objectFit: 'cover',
  at: { x: 960, y: 0, w: 960, h: 1080 } }
```

***

## `type: 'shape'`

A vector shape — rectangle, circle, ellipse, triangle, or line. Supports solid fills, CSS gradients, structured fill stacks, opacity, stroke, and corner radius.

<ParamField path="type" type="&#x22;shape&#x22;" required />

<ParamField path="shape" type="'rectangle' | 'circle' | 'ellipse' | 'triangle' | 'line'" required>The shape kind.</ParamField>
<ParamField path="fill" type="string">Solid fill color as a CSS color string.</ParamField>
<ParamField path="gradient" type="string">Raw CSS gradient string, e.g. `'linear-gradient(135deg, #667eea, #764ba2)'`.</ParamField>

<ParamField path="fills" type="Fill[]">
  Structured fill stack — an array of `Fill` objects (solid, gradient, image, shader). Rendered bottom-to-top. See [Fills Reference](/api/fills-reference).
</ParamField>

<ParamField path="opacity" type="number">Fill opacity from `0` (transparent) to `1` (opaque). Does not affect stroke.</ParamField>
<ParamField path="stroke" type="string">Stroke color as a CSS color string.</ParamField>
<ParamField path="strokeWidth" type="number">Stroke thickness in pixels.</ParamField>
<ParamField path="radius" type="number">Corner radius in pixels (rectangles only).</ParamField>
<ParamField path="x1" type="number">Line start X, relative to the layer box in 0–1 coordinates (lines only).</ParamField>
<ParamField path="y1" type="number">Line start Y (lines only).</ParamField>
<ParamField path="x2" type="number">Line end X (lines only).</ParamField>
<ParamField path="y2" type="number">Line end Y (lines only).</ParamField>
<ParamField path="arrowStart" type="boolean">Add an arrowhead at the start of the line.</ParamField>
<ParamField path="arrowEnd" type="boolean">Add an arrowhead at the end of the line.</ParamField>

```typescript theme={null}
// Rounded rectangle with a brand fill
{ type: 'shape', shape: 'rectangle',
  fills: [solidFill('var(--slide-brand)')],
  radius: 12,
  at: { x: 160, y: 800, w: 300, h: 60 } }

// Arrow line
{ type: 'shape', shape: 'line', stroke: '#94A3B8', strokeWidth: 2,
  arrowEnd: true, x1: 0, y1: 0.5, x2: 1, y2: 0.5,
  at: { x: 200, y: 540, w: 400, h: 4 } }
```

***

## `type: 'icon'`

An SVG icon layer from the Ablo icon library.

<ParamField path="type" type="&#x22;icon&#x22;" required />

<ParamField path="icon" type="string" required>Icon key, e.g. `'rocket'`, `'bar-chart'`, `'arrow-right'`, `'check-circle'`.</ParamField>
<ParamField path="color" type="string">Icon color. Accepts any CSS color or theme variable.</ParamField>

```typescript theme={null}
{ type: 'icon', icon: 'rocket', color: 'var(--slide-brand)',
  at: { x: 880, y: 480, w: 160, h: 160 } }
```

***

## Full example

The following creates a deck with a single content slide that uses multiple layer types together.

```typescript theme={null}
import Decks, { solidFill } from '@abloatai/decks';

const ablo = new Decks(process.env.ABLO_API_KEY!);

await ablo.decks.create({
  title: 'Q3 Investor Update',
  slides: [
    {
      title: 'Key Metrics',
      layers: [
        // Background rectangle
        {
          type: 'shape',
          shape: 'rectangle',
          fills: [solidFill('#0F172A')],
          at: { x: 0, y: 0, w: 1920, h: 1080 },
          z: 0,
        },
        // Slide heading
        {
          type: 'text',
          text: 'Key Metrics — Q3 2024',
          style: 'h1',
          color: '#F1F5F9',
          at: { x: 160, y: 80, w: 1200, h: 110 },
          z: 1,
        },
        // KPI labels
        {
          type: 'bullets',
          items: ['ARR $4.2M', 'NRR 118%', 'CAC payback 9 months'],
          style: 'body1',
          color: '#CBD5E1',
          bulletColor: '#3B82F6',
          bulletStyle: 'arrow-right',
          at: { x: 160, y: 240, w: 600, h: 400 },
          z: 2,
        },
        // Revenue chart
        {
          type: 'bar',
          data: [
            { label: 'Q1', value: 2.1 },
            { label: 'Q2', value: 2.8 },
            { label: 'Q3', value: 3.4 },
          ],
          valueFormat: '$0.0"M"',
          dataLabels: true,
          cagrArrow: true,
          at: { x: 900, y: 160, w: 860, h: 720 },
          z: 2,
        },
        // Company logo
        {
          type: 'image',
          url: 'https://cdn.example.com/logo.svg',
          objectFit: 'contain',
          at: { x: 80, y: 30, w: 180, h: 54 },
          z: 3,
        },
      ],
    },
  ],
});
```