Image layers

Draw an uploaded photo or a chosen design onto the product, masked into a shape and fitted the way you want.

An image layer draws a picture onto the product photo. The image is either a file the customer uploaded, or an image attached to the value they selected.

Applies to: File upload, and eight selection types: Dropdown, Color dropdown, Image dropdown, Radio button, Checkbox, Button, Color swatch, Image swatch.

Where the image comes from

Option type	The layer draws
File upload	The file the customer uploaded
The eight selection types	The image attached to the option value they selected

For selection types, each value needs its own image in the values table. See Working with option values.

Settings specific to image layers

Setting	Default	What it does
Image shape	A supplied shape	The shape the image is masked into. Choose a preset, or upload your own
Background mode	Cover	How the image fits inside that shape

The remaining settings are shared with text layers: position, width, height, opacity, rotation, crop area, and customer controls. See Position, size, and rotation.

Shape decides the window; background mode decides how the image fills it.

Image shape

The image is masked into a shape, so it appears as part of the product rather than as a rectangle on top of it.

Select one of the supplied shapes, or upload your own. Use a custom shape to match an unusual aperture, such as a locket, a heart-shaped frame, or a phone camera cut-out.

Product	Shape
A rectangular photo frame	A rectangle matching the aperture's proportions
A round locket or badge	A circle
A phone case with a camera cut-out	A custom shape you upload
A printed t-shirt panel	A rectangle matching the print area
A heart-shaped pendant	A custom shape

Match the shape's proportions to your real aperture. A square mask on a portrait frame crops the customer's photo unexpectedly.

Background mode

Five options for how the image fits the shape.

Mode	Behavior	Trade-off
Stretch	Forces the image to fill the shape exactly	Distorts anything whose proportions differ from the shape
Cover	Scales until the shape is filled, keeping proportions	Crops the edges. The default, and usually right
Contain	Scales until the whole image fits inside	Leaves empty space at two edges
Full width	Fills the shape's width	May overflow or fall short vertically
Full height	Fills the shape's height	May overflow or fall short horizontally

Which value to use

Situation	Mode
Customers upload their own photos, any shape	Cover — always fills the window, never distorts
The whole image must be visible, cropping unacceptable	Contain, and say in help text that empty space may show
Your own value images, all cropped consistently	Cover or Stretch — with matching proportions they behave the same
A panoramic or banner-shaped area	Full width
A tall narrow area	Full height

Do not use Stretch for customer uploads. A portrait photo placed in a landscape-shaped area will appear distorted. Cover crops the image instead, producing a more natural result.

Use Cover together with the image editor for the upload option, so customers can crop their photos to the correct shape before they appear in the preview.

Example configuration

For an option that lets the customer upload a photo and see it in a frame:

Setting	Value
Option type	File upload, required
Allowed extensions	jpg, jpeg, png
Enable image editor	On, so customers crop before uploading
Help text	JPG or PNG, at least 1500 × 1500 pixels
Image shape	Matching your frame aperture
Background mode	Cover
Width and height	Sized to the aperture in the photo
Crop area	On, matching the aperture
Allow customers to	Change position and Resize, so they can frame their photo

Selection types as image layers

To let the customer select a design instead of uploading one:

1

Add a selection option with an image per value

Use an Image swatch for a visible grid, or an Image dropdown for a long list.

2

Upload a design image on each value

Add the image in the values table. Use consistent proportions across all values.

3

Turn on the Personalizer

Then set the image shape and background mode.

4

Position and size the layer

Set where the design appears on the product.

5

Leave customer controls off

You have already positioned the design, so the customer does not need to move it.

A multi-select option can create several image layers at the same time, which may cause them to overlap. Either limit the option to one selection or position the layers so they do not overlap.

Notes

• An image layer displays nothing until a file is uploaded or a value with an image is selected. Unlike text layers, it has no default value.

• Uploaded images can be large. Use Cover and a Crop area to keep the preview within the defined area.

• Uploaded images are displayed at their original resolution, so a small file may appear blurry when enlarged. Specify a minimum image size in the help text.

• A custom shape is uploaded to your store's files and can be reused across multiple options.