Image, Shape & Icon Layers: Visual Slide Components

Beyond text and charts, the Decks SDK lets you place images, vector shapes, and icons anywhere on a slide. Images are rehosted automatically so any public URL works without pre-processing. Shapes give you filled and stroked vector primitives — rectangles, circles, triangles, and lines — with support for solid fills, CSS gradients, and structured fill stacks. Icons draw from the Ablo icon library using short key strings. All three layer types use the same at coordinate system as every other layer type.

Images

The image() builder and the { type: 'image' } inline syntax both accept a public HTTPS URL and optional display options.

Inline syntax

const layer = {
  type: 'image' as const,
  url: 'https://images.unsplash.com/photo-1518770660439-4636190af475?w=1200',
  objectFit: 'cover',
  at: { x: 960, y: 80, w: 880, h: 920 },
};

Builder function syntax

Pass a URL string for the simplest case, or an options object for more control:

import { image } from '@abloatai/decks';

// Shorthand — URL only, defaults to objectFit: 'cover'
const layer = image('https://images.unsplash.com/photo-1518770660439-4636190af475?w=1200');

// Options object
const layer = image({
  url: 'https://cdn.example.com/product-screenshot.png',
  objectFit: 'contain',
  width: 1200,
  height: 800,
});

Image options

url

string

required

A public HTTPS URL. External URLs are automatically rehosted to the Ablo CDN server-side when the deck is committed — you don’t need to pre-process or proxy them. Must be a valid URL string.

objectFit

'cover' | 'contain' | 'fill'

How the image fills its layer box. 'cover' (default) crops to fill while preserving aspect ratio. 'contain' letterboxes the image to fit without cropping. 'fill' stretches the image to exactly fill the box.

width

number

Intrinsic image width in pixels. Helps the renderer compute the correct crop when the intrinsic dimensions differ significantly from the layer box.

height

number

Intrinsic image height in pixels.

Using local or private images

External public URLs are rehosted automatically. For images that aren’t publicly accessible — files on your filesystem, authenticated CDN assets, or generated images — upload them first to get a permanent Ablo CDN URL:

import { Decks } from '@abloatai/decks';

const ablo = new Decks({ apiKey: process.env.ABLO_API_KEY });

// Upload a local file buffer
const { url } = await ablo.images.upload(fs.readFileSync('./chart-export.png'), {
  filename: 'chart-export.png',
  contentType: 'image/png',
});

// Now use the returned CDN URL in a layer
const layer = image(url);

See the Image Uploads guide for full upload options including multipart forms and presigned URLs.

Example: image with rounded shape overlay

import { image, shape } from '@abloatai/decks';

// Full-bleed background image
const bg = {
  type: 'image' as const,
  url: 'https://images.unsplash.com/photo-1551288049-bebda4e38f71?w=1920',
  objectFit: 'cover' as const,
  at: { x: 0, y: 0, w: 1920, h: 1080 },
};

// Semi-transparent overlay to improve text legibility
const overlay = shape({
  shape: 'rectangle',
  fill: 'rgba(0, 0, 0, 0.45)',
  radius: 0,
});

Shapes

The shape() builder renders a vector primitive. Use shapes for backgrounds, dividers, decorative accents, callout boxes, and connector lines. All shapes accept a fill color, gradient, or structured fill stack, plus stroke and opacity controls.

Inline syntax

const layer = {
  type: 'shape' as const,
  shape: 'rectangle',
  fill: '#5B4CF5',
  radius: 12,
  opacity: 0.9,
  at: { x: 80, y: 80, w: 400, h: 200 },
};

Builder function syntax

import { shape } from '@abloatai/decks';

const layer = shape({
  shape: 'rectangle',
  fill: '#5B4CF5',
  radius: 12,
  opacity: 0.9,
});

ShapeKind values

shape

'rectangle' | 'circle' | 'ellipse' | 'triangle' | 'line'

required

The geometric primitive to render. 'circle' renders a perfect circle (use square at dimensions). 'ellipse' renders a stretched oval. 'triangle' renders a filled triangle pointing up. 'line' renders a line between two endpoints — see Line shapes below.

Fill options

You can fill a shape with a solid color, a CSS gradient, or a structured fill stack.

fill

string

Solid fill color as a CSS color string, e.g. '#5B4CF5', 'rgba(91, 76, 245, 0.2)', or 'var(--slide-brand)'.

gradient

string

CSS gradient string, e.g. 'linear-gradient(135deg, #5B4CF5 0%, #818CF8 100%)'. When set, takes precedence over fill.

fills

Fill[]

A structured fill stack for advanced compositing — solid layers, gradients, mesh gradients, image fills, and shader fills stacked in order. See the Fills reference for the full schema.

opacity

number

Shape opacity from 0 (fully transparent) to 1 (fully opaque). Applies to the fill only, not the stroke.

Stroke options

stroke

string

Stroke color as a CSS color string.

strokeWidth

number

Stroke thickness in pixels. Set to 0 to suppress the stroke entirely.

Rectangle radius

radius

number

Corner radius in pixels for 'rectangle' shapes. Applied uniformly to all four corners. Ignored for other shape kinds.

Shape examples

import { shape } from '@abloatai/decks';

const card = shape({
  shape: 'rectangle',
  gradient: 'linear-gradient(135deg, #5B4CF5 0%, #818CF8 100%)',
  radius: 16,
  opacity: 1,
});

Line shapes

The 'line' shape kind draws a line between two points within the layer box. Use x1, y1, x2, y2 to position endpoints relative to the layer frame (the at box). Add arrowheads with arrowStart and arrowEnd.

number

Horizontal start coordinate, relative to the layer box origin.

number

Vertical start coordinate, relative to the layer box origin.

number

Horizontal end coordinate, relative to the layer box origin.

number

Vertical end coordinate, relative to the layer box origin.

arrowStart

boolean

When true, renders an arrowhead at the start endpoint (x1, y1).

arrowEnd

boolean

When true, renders an arrowhead at the end endpoint (x2, y2).

import { shape } from '@abloatai/decks';

// Horizontal divider line
const divider = shape({
  shape: 'line',
  stroke: '#e5e7eb',
  strokeWidth: 1,
  x1: 0,
  y1: 0,
  x2: 1,
  y2: 0,
});

// Arrow pointing right with arrowhead
const arrow = shape({
  shape: 'line',
  stroke: '#5B4CF5',
  strokeWidth: 2,
  x1: 0,
  y1: 0.5,
  x2: 1,
  y2: 0.5,
  arrowEnd: true,
});

Line endpoints (x1, y1, x2, y2) are in the coordinate space of the layer box defined by at. A value of 0 maps to the left/top edge and 1 maps to the right/bottom edge (normalized), so a horizontal line from left to right is x1: 0, y1: 0.5, x2: 1, y2: 0.5.

Icons

The icon() builder places a single icon from the Ablo icon library. Icons are identified by a short key string — the same keys used in the Ablo editor’s icon picker. You can optionally set a fill color; the icon inherits the deck theme’s foreground color when color is omitted.

Inline syntax

const layer = {
  type: 'icon' as const,
  icon: 'rocket',
  color: '#5B4CF5',
  at: { x: 880, y: 480, w: 160, h: 160 },
};

Builder function syntax

Pass a key string for the simplest case, or an options object when you want to set a color:

import { icon } from '@abloatai/decks';

// Shorthand — key string only
const layer = icon('rocket');

// Options object with color
const layer = icon({
  icon: 'bar-chart',
  color: 'var(--slide-brand)',
});

Icon options

icon

string

required

Icon key string from the Ablo icon library, e.g. 'rocket', 'bar-chart', 'check-circle', 'globe'. Key names follow kebab-case.

color

string

Fill color for the icon as a CSS color string. When omitted, the icon uses the deck theme’s default foreground color.

Icon grid example

import { icon } from '@abloatai/decks';

const icons = [
  { key: 'bar-chart',    label: 'Analytics',    x: 120 },
  { key: 'globe',        label: 'Global Reach',  x: 440 },
  { key: 'check-circle', label: 'Reliability',   x: 760 },
  { key: 'rocket',       label: 'Performance',   x: 1080 },
];

const layers = icons.flatMap(({ key, label, x }) => [
  {
    type: 'icon' as const,
    icon: key,
    color: 'var(--slide-brand)',
    at: { x, y: 400, w: 120, h: 120 },
  },
  {
    type: 'text' as const,
    text: label,
    style: 'caption' as const,
    align: 'center' as const,
    at: { x: x - 40, y: 540, w: 200, h: 48 },
  },
]);

Scale icons generously — a 120×120 icon sits comfortably on a 1920×1080 slide as a standalone visual. For inline decorative use alongside text, 32×32 or 48×48 works well. Always set equal w and h values to preserve the icon’s square aspect ratio.

​Images

​Inline syntax

​Builder function syntax

​Image options

​Using local or private images

​Example: image with rounded shape overlay

​Shapes

​Inline syntax

​Builder function syntax

​ShapeKind values

​Fill options

​Stroke options

​Rectangle radius

​Shape examples

​Line shapes

​Icons

​Inline syntax

​Builder function syntax

​Icon options

​Icon grid example

Images

Inline syntax

Builder function syntax

Image options

Using local or private images

Example: image with rounded shape overlay

Shapes

Inline syntax

Builder function syntax

ShapeKind values

Fill options

Stroke options

Rectangle radius

Shape examples

Line shapes

Icons

Inline syntax

Builder function syntax

Icon options

Icon grid example