Preset scene components (painter.components)

painter.components exposes small factories. Every toLayers(options) returns ordinary SceneLayer[] that you can spread into renderScene, SceneBuilder.addLayers, or template insertions.

They are static rendering helpers, not DOM widgets. They do not carry accessibility semantics such as alt text, ARIA labels, or reading order. If the generated image is shown in HTML or another accessible UI, provide the appropriate accessible name/description in that surrounding UI.

All built-ins validate finite/positive geometry and relevant resource limits before returning layers.

#Common pattern

1import { ApexPainter } from "apexify.js";2 3const painter = new ApexPainter({ type: "buffer" });4 5const layers = [6  ...painter.components.badge.toLayers({7    text: "Beta",8    x: 24,9    y: 24,10    paddingX: 10,11    paddingY: 6,12    radius: 999,13    background: "#312e81",14    color: "#e0e7ff",15    fontSize: 13,16  }),17  ...painter.components.progressBar.toLayers({18    x: 24,19    y: 64,20    width: 320,21    height: 14,22    value: 72,23    max: 100,24    background: "#1e293b",25    fill: "#38bdf8",26    radius: 6,27    showLabel: true,28    labelColor: "#e2e8f0",29  }),30];31 32const png = await painter.renderScene({33  width: 420,34  height: 140,35  background: { colorBg: "#020617" },36  layers,37});

Earlier entries paint below later entries.

#badge.toLayers

BadgeToLayersOptions: required text, x, y; optional paddingX, paddingY, radius, background, color, fontSize.

The component estimates pill width from text length/font size, enforces non-negative padding/radius and positive font size, and clamps the corner radius to the produced box.

#progressBar.toLayers

ProgressBarToLayersOptions: x, y, width, height, value; optional max (default 100), track background, fill, radius, showLabel, labelColor.

• Width/height and max must be positive.
• value is clamped into [0, max].
• The fill never exceeds the declared progress-bar width.
• Zero progress emits no fill layer.

#avatar.toLayers

AvatarToLayersOptions: source (non-empty path/URL string or Buffer), x, y, size, optional borderColor, borderWidth.

The image uses circular clipping. A positive borderWidth with borderColor emits a ring layer behind the clipped image. Invalid/empty sources and border widths larger than the avatar size are rejected.

#card.toLayers

CardToLayersOptions: x, y, width, height, optional radius, background, borderColor / borderWidth, title, body, title/body font sizes and colors, padding.

The component emits a rounded panel followed by optional text layers. Padding and border width are validated so a positive content area remains. Text uses the available card width as its wrap bound.

#watermark.toLayers

WatermarkToLayersOptions: text, canvasWidth, canvasHeight, optional position (bottom-right, bottom-left, top-right, top-left, center), fontSize, color, margin.

The watermark is canvas-aware: invalid position values are rejected, text must fit the supplied canvas dimensions, and corner margins may not push the estimated watermark outside the canvas. Use it late in the layer array when it should paint on top.

#Mixing with arbitrary scene layers

1const ui = [2  ...painter.components.card.toLayers({3    x: 32,4    y: 32,5    width: 360,6    height: 200,7    radius: 16,8    background: "#0f172a",9    borderColor: "#334155",10    borderWidth: 1,11    title: "Usage",12    titleFontSize: 18,13    body: "You are at 72% of your quota.",14    bodyFontSize: 14,15    padding: 16,16  }),17  ...painter.components.watermark.toLayers({18    text: "CONFIDENTIAL",19    canvasWidth: 480,20    canvasHeight: 280,21    position: "center",22    fontSize: 36,23    color: "#f9731644",24  }),25];26 27await painter.renderScene({28  width: 480,29  height: 280,30  background: { colorBg: "#020617" },31  layers: ui,32});

The option types are exported from apexify.js and the type-only apexify.js/types subpath.