Elements

Elements are the building blocks placed on the canvas — text, images, SVGs, and their variants. Each element has a type, source, title, and a parameters object that controls its appearance and behavior.

Element Types

Type	Source	Description
text	Text content	Single-line editable text.
textbox	Text content	Multi-line text with auto-wrap and fixed width.
curved-text	Text content	Text rendered on a circular arc.
neon-text	Text content	Text with a neon glow effect.
engraved-text	Text content	Text with an engraved look (fixed opacity).
image	Image URL	Raster image (PNG, JPEG) or SVG. SVGs with multiple paths become CVSVGGroup automatically.

Adding Elements

Via product data

const product = {
    views: [{
        title: 'Front',
        elements: [
            {
                type: 'text',
                source: 'Hello World',
                title: 'Greeting',
                parameters: {
                    left: 400, top: 200,
                    fontSize: 32, fill: '#333',
                    draggable: true, editable: true,
                },
            },
        ],
    }],
};

Programmatically

await canvas.addElement('text', 'Hello World', 'Greeting', {
    left: 400, top: 200,
    fontSize: 32, fill: '#333',
    draggable: true, editable: true,
});

await canvas.addElement('image', '/images/logo.png', 'Logo', {
    left: 450, top: 300,
    scaleX: 0.5, scaleY: 0.5,
});

Base Parameters (ElementParameters)

All element types share these parameters:

Position & Transform

Parameter	Type	Default	Description
left	number	—	X position in canvas pixels.
top	number	—	Y position in canvas pixels.
angle	number	0	Rotation in degrees.
scaleX	number	1	Horizontal scale factor.
scaleY	number	1	Vertical scale factor.
opacity	number	1	Opacity (0-1).
flipX	boolean	false	Flip horizontally.
flipY	boolean	false	Flip vertically.
originX	'left' | 'center' | 'right'	'left'	Horizontal origin point.
originY	'top' | 'center' | 'bottom'	'top'	Vertical origin point.

Permissions

Parameter	Type	Default	Description
draggable	boolean	true	Allow user to drag.
rotatable	boolean	true	Allow user to rotate.
resizable	boolean	true	Allow user to resize.
removable	boolean	true	Allow user to remove.
copyable	boolean	true	Allow user to duplicate.
editable	boolean	true	Allow user to edit content.
locked	boolean	false	Lock element (must unlock via Manage Layers).
lockUniScaling	boolean	true	Lock proportional scaling.
uniScalingUnlockable	boolean	false	Allow user to unlock proportional scaling.
minScaleLimit	number	0.01	Minimum scale factor.

Colors

Parameter	Type	Default	Description
fill	string | false	—	Fill color. false = use original.
colors	string | string[] | false	false	Color options. '#hex' = color picker, ['#a','#b'] = swatches, false = disabled.
colorLinkGroup	string | false	false	Sync color across elements with the same group name.
colorPrices	Record<string, number>	—	Per-color pricing: { "#ff0000": 5.00 }.

Layering

Parameter	Type	Default	Description
z	number	-1	Z-index position. -1 = add on top.
zChangeable	boolean	true	Allow user to change z-position.
topped	boolean	false	Always keep on top of stack.

Behavior

Parameter	Type	Default	Description
boundingBox	BoundingBoxValue	—	Constrain element movement.
autoCenter	boolean	true	Center in canvas/bounding box when added.
autoSelect	boolean	true	Select element when added.
replace	string	—	Replace elements with matching replace value.
replaceInAllViews	boolean	false	Replace in all views, not just current.
fixed	boolean	false	Element persists when product changes.
price	number	0	Price for this element.
sku	string	—	SKU identifier for order processing.
excludeFromExport	boolean	false	Exclude from SVG/image export.
patterns	string[]	—	Pattern image URLs for fill.
printAreaId	string | null	—	Assign to a specific print area.

Shadow

Parameter	Type	Default	Description
shadowColor	string	—	Shadow color.
shadowBlur	number	0	Shadow blur radius.
shadowOffsetX	number	0	Shadow X offset.
shadowOffsetY	number	0	Shadow Y offset.

Text Parameters

Text elements (text, textbox, curved-text, neon-text, engraved-text) accept additional parameters:

Parameter	Type	Default	Description
fontFamily	string	'Arial'	Font family name.
fontSize	number	18	Font size in pixels.
fontWeight	string	'normal'	Font weight ('normal', 'bold').
fontStyle	string	'normal'	Font style ('normal', 'italic').
textAlign	string	'left'	Text alignment.
lineHeight	number	1.16	Line height multiplier.
letterSpacing	number	0	Additional letter spacing.
textDecoration	string	''	Text decoration ('underline').
stroke	string | null	null	Text stroke/outline color.
strokeWidth	number	0	Stroke width.
strokeColors	string[]	[]	Available stroke colors.
maxLength	number	0	Max characters (0 = unlimited).
maxLines	number	0	Max lines (0 = unlimited, textbox only).
minFontSize	number	1	Minimum font size.
maxFontSize	number	1000	Maximum font size.
textTransform	TextTransform	'none'	Transform: 'none', 'uppercase', 'lowercase'.
curveRadius	number	100	Curve radius (curved-text only).
curveReverse	boolean	false	Reverse curve direction.
textPlaceholder	boolean	false	Names & Numbers name placeholder.
numberPlaceholder	boolean | number[]	false	Names & Numbers number placeholder.
textLinkGroup	string	—	Sync text content across elements.
widthFontSize	number	0	Auto-adjust font size to keep the text at this width; disables manual resizing. Mutually exclusive with heightFontSize.
heightFontSize	number	0	Auto-adjust font size to keep the text at this height; disables manual resizing. Mutually exclusive with widthFontSize.

Image Parameters

Image elements accept additional parameters:

Parameter	Type	Default	Description
filter	string | null | false	null	Image filter: 'grayscale', 'sepia', etc.
colorMode	ColorBlendMode	—	Color blend mode for tinting.
scaleMode	ScaleMode	—	How to scale when fitting: 'fit', 'cover'.
resizeToW	number | string	0	Resize to this width.
resizeToH	number | string	0	Resize to this height.
uploadZone	boolean	false	Use as clickable upload zone.
svgFill	string | string[] | false	—	Per-path SVG colors.
imageProxy	boolean	true	Set false to always render the full-resolution original (opt out of large-image proxying, see below).
proxySource	string	—	URL of a server-hosted downscaled variant rendered instead of source (hybrid proxy loading, see below). Requires originalWidth/originalHeight.

Large Image Handling

Canvas memory is driven by decoded pixels (width × height × 4 bytes), not file size — a few high-resolution photos can crash mobile browsers. By default, raster images whose natural dimension exceeds the imageProxyMaxDimension option (default 1600, with 25% slack) are downscaled to an in-memory proxy for on-canvas editing:

• The element's source, logical dimensions, and scaleX/scaleY are unchanged — serialization and orders always reference the full-resolution original.
• Print exports (server-side and exportPrintAreaToSVG()) render from the original, never the proxy.
• DPI warnings and the size tooltip rate the original via originalWidth/originalHeight (serialized in the element JSON for proxied images, alongside originalFileSize when known).
• isProxy is exposed at runtime on the element; it is not serialized.
• SVGs are never proxied (vector). Raise imageProxyMaxDimension for sharper on-screen zoom at the cost of memory, or set 0 to always render originals.
• Per-element opt-out: set imageProxy: false on an element to always render its original. Combined with the parameter cascade this also works group-wise — e.g. imageParameters: { imageProxy: false } exempts configured product images while user uploads stay proxied, or customImageParameters: { imageProxy: false } for the reverse.
• Hybrid (server-side) proxies: when an element carries proxySource plus originalWidth/originalHeight, the canvas loads only that server-hosted variant — the original is never fetched client-side, saving bandwidth on top of memory. The uploads module sets these automatically when the upload server returns image_proxy_src (see the playground's upload-image.php for a reference), and Pixabay picks use Pixabay's own webformatURL as variant for high-res images. proxySource is serialized, so restored designs keep skipping the original; if the variant fails to load, the original loads with client-side proxying as fallback. Orders and exports are identical in both modes: source always stays the full-resolution original.

For the full picture — both proxying modes, configuration, per-group opt-out, the upload server contract, and automatic wiring — see the Image Proxy Loading guide.

Custom Parameters

When users add their own text or images (via the UI modules), you can constrain what they're allowed to do using customTextParameters and customImageParameters in options:

const options = {
    customTextParameters: {
        maxLength: 50,
        minFontSize: 12,
        maxFontSize: 72,
        colors: ['#000000', '#ffffff', '#ff0000'],
        draggable: true,
        resizable: true,
        removable: true,
    },
    customImageParameters: {
        draggable: true,
        resizable: true,
        removable: true,
        minW: 100,    // Min upload width (px)
        minH: 100,    // Min upload height (px)
        maxSize: 10,  // Max file size (MB)
        minDPI: 150,  // Min DPI for quality
    },
};

Parameter Cascade

Parameters merge in this order (each level overrides the previous):

elementParameters → textParameters → customTextParameters
elementParameters → imageParameters → customImageParameters

And options cascade through:

OPTION_DEFAULTS → mainOptions → viewOptions → printAreaProfile

See Options Cascade for details.

Next Steps

• Products & Views — How elements fit into the data model
• Print Areas — Constraining elements to printable regions
• Events — Reacting to element changes