Patch Preview Setup Guide

Live patch configurator for the Vero theme. Customers pick a shape, leatherette materials and an engraving color, upload artwork or choose a design from the gallery, and see the result on the product photo before adding to cart.

This guide covers merchant setup, storefront behavior, and launch testing.

1. Create the metaobject definitions

Three definitions are needed. Create them in Settings → Custom data → Metaobjects. Field keys must match exactly; display names can be anything.

`patch_material`

One entry per leatherette. This is what makes the preview look like real material rather than a flat color swatch.

Field key	Type	Required	Notes
`name`	Single line text	Yes	Shown under the swatch.
`texture_image`	File (image)	Yes	The full material texture. 1400px on the long edge is plenty.
`swatch_image`	File (image)	No	Small crop for the selector. Falls back to `texture_image`.
`fallback_color`	Color	Yes	Painted until the texture loads, and if it ever fails to.
`texture_scale`	Decimal	No	Default `1`. Above 1 zooms into the grain.
`texture_x`	Decimal	No	Default `50`. Horizontal focal point, as a percentage.
`texture_y`	Decimal	No	Default `50`. Vertical focal point, as a percentage.
`texture_rotation`	Decimal	No	Default `0`. Useful for directional grain.
`engraves_to`	Metaobject → `patch_engraving_color`	No	The one color this material burns to. See below.
`engraving_colors`	List of metaobjects → `patch_engraving_color`	No	Narrows the choice instead of fixing it. See below.
`sku`	Single line text	No	Your reference. Carried through to the order payload.

Give each entry a clear handle (rawhide, black-pebble, saddle-tan). The handle is the id used in settings and stored on the order.

Texture images: upload a flat, evenly lit, seamless-ish crop of the material. Around 1400px on the long edge keeps files small while staying sharp when the patch is shown large. Avoid shadows or perspective baked into the image.

Swatch images: upload a ~240px crop. The block requests a small version of whatever you upload, but a purpose-made crop reads better at swatch size.

`patch_engraving_color`

Field key	Type	Required	Notes
`name`	Single line text	Yes	Shown under the swatch.
`color`	Color	Yes	The engraving color.

Engraving color and patch material stay separate concepts: the material is the body of the patch, the engraving color is what the artwork becomes.

Materials that engrave to a fixed color

Laser engraving burns through the top layer of leatherette and exposes the core, so most materials can only ever produce one result — a black/tan sheet engraves tan no matter what. Set engraves_to on those materials.

When a material has engraves_to, the color swatches are replaced by a short sentence ("Engraves to Tan — the color Black Pebble reveals when it is engraved"), the preview uses that color, and the customer cannot pick something the material cannot physically do. That sentence, like every other string in the block, lives in locales/en.default.json under blocks.patch_designer — the key is engraving_fixed, and [color] and [material] are substituted at runtime.

There are three levels, and the first one that applies wins:

Material setup	What the customer sees
`engraving_colors` lists two or more	Swatches limited to those colors.
`engraves_to` is set, on its own	No choice. A note stating the resulting color.
Neither is set	Every color in the set's `engraving_colors`.

Listing colors wins over engraves_to deliberately. Setting both reads as "this material offers these colors", so showing only one would look like a bug rather than a setting. When both are present the fixed color is offered first, as the default.

Colors referenced by a material — through either field — do not need to appear in the set's shared engraving_colors list. They register themselves. A core shade used by exactly one material therefore needs no extra admin setup, and a color you list on a material will never silently vanish because you forgot to add it to the set as well.

Switching material re-checks the current engraving color and moves it to the first valid option if the old one is no longer possible, so the two selectors can never disagree.

`patch_material_set`

A container so one product can point at a whole library with a single setting.

Field key	Type	Required
`name`	Single line text	No
`materials`	List of metaobjects → `patch_material`	Yes
`engraving_colors`	List of metaobjects → `patch_engraving_color`	No

Create at least one entry, for example Standard leatherette, and add every material you offer.

The set's engraving_colors is the list used by materials that do not specify their own, so it is worth filling in. It is not required: colors named on the materials themselves are picked up either way.

name is what the customer reads in the set picker, so give it the name you use on the storefront rather than an internal one. Without it the entry's display name is used.

Splitting a large library into sets

Stores that carry a few hundred colors should create one set per family — Heritage, Premium, Carbon fiber — rather than one set holding everything. Select them all on the block and the customer picks the family first and then the color, instead of scrolling a wall of swatches.

A color can appear in more than one set. Two entries sharing a handle stay separate, so Black in Heritage and Black in Premium are treated as the different materials they are.

Non-preview material groups

Materials such as tri-layer acrylic can share the same artwork flow without a simulated material or engraving setup. Select the existing parent swatch_group under Non-preview swatch container, then enter the fields to offer under Non-preview group fields, separated by commas. For example, tri_layer,carbon_fiber,camo creates top-level Tri Layer, Carbon Fiber, and Camo choices. Each field's referenced items appear underneath as visual swatches. Their names appear in desktop hover/focus tooltips and mobile tap-to-open tooltips rather than as captions below the swatches.

Once a non-preview source is configured, the material picker starts unselected and must be completed first. A non-preview choice keeps shape, artwork/design, and optional text collection, but hides preview material colors, engraving, placement controls, and the on-product overlay. It also suppresses generated mockup and vector files so an inaccurate preview cannot reach the order.

2. Add the block to a product

Open the product template in the theme editor.
Inside Buy buttons, add the Patch designer block.
Set Material sets to the patch_material_set entries you created.
Set the shapes you want to offer and the default shape.

Available shape ids: rectangle, rounded-rectangle, square, circle, oval, shield, badge, hexagon, diamond. Enter them comma separated. Contour is not listed here — turn on Allow Contour shape to offer cutting the patch to the artwork outline as an extra swatch.

To offer shapes of your own, see Your own shapes.

Settings worth knowing

Setting	What it does
Default material set	Handle of the set to open on. Only used when more than one set is selected.
Non-preview swatch container	Existing parent `swatch_group` containing the unsupported material fields.
Non-preview group fields	Comma-separated field keys such as `tri_layer,carbon_fiber,camo`.
Material group fees	Optional group-specific hidden fee products, with one-time/per-item and waiver rules.
Custom shape set	A `patch_shape_set` entry holding your own SVG shapes. Optional.
Allow Contour shape	Adds a Contour swatch that cuts the patch to the artwork outline.
Contour border	How much material is left around the artwork, as a percentage.
Allow engraving / UV	Turn either production method off. If only one is on, the chooser is hidden.
Allow gallery designs	Lets the existing design picker supply artwork.
Hide upload with design	Hides the upload field once a gallery design is selected.
Attach PNG mockup	Adds the selected product photo with the configured patch placement to the order.
Attach SVG artwork	Adds a vector version of the patch to the order.
Required product tag	Shows the block only on products with that tag.
Gallery selector	CSS selector for the media gallery. Leave as `media-gallery` unless yours differs.

Defaults for materials and engraving color are entered as handles, for example rawhide. Leave blank to use the first option in the list. A default engraving color is ignored when the starting material engraves to a fixed color.

Wording

Every customer-facing string is a translation rather than a block setting, so it can be edited in Content → Default content in admin, or directly in locales/en.default.json under blocks.patch_designer, and translated per market like the rest of the theme.

3. Your own shapes (optional)

The built-in shapes cover the common patch outlines. To offer something else, upload the outline as an SVG and the theme traces it into a patch shape.

Create two more definitions

patch_shape — one entry per shape:

Field name	Type	Required	Notes
`name`	Single line text	Yes	Shown under the shape button.
`svg`	File	Yes	The outline. See the file requirements below.
`artwork_inset`	Integer	No	Margin kept clear around artwork, as a percentage. Defaults to 18.

patch_shape_set — one entry per product family:

Field name	Type	Required	Notes
`shapes`	List of `patch_shape` entries	Yes	The shapes on offer.

Then set the block's Custom shape set to that entry. Your shapes appear after the built-in ones, whether or not the Available shapes list mentions them, so uploading one is all it takes to offer it.

What the SVG needs to be

A silhouette, not a drawing. Only the outline matters. Color, gradients and layers are ignored.
Filled, not stroked. Export the outline as a filled shape. A shape drawn only with a stroke still works, but the outline traces the centre of the stroke rather than its edge.
Any size. The shape is scaled to fit the patch, so the artboard dimensions do not matter. Its proportions are kept.
Holes are kept. A shape with a cut-out, like a ring, stays cut out.

Alignment is shared by every shape on a photo, so a shape with unusual proportions may want its own look. Check it against the tallest and widest shapes you offer before going live.

4. Position the preview on the product photo

You align once per product, not once per photo. Every colorway of a style is shot on the same jig at the same framing, so one set of numbers covers all of them — eighty variants included. Alignment is stored as percentages of the product image, so those numbers also hold at every screen size.

Open the product page with ?patch-align=1 on the end of the URL.
A dark panel appears in the corner and the patch gets a dashed outline.
Drag the patch to move it. Use the bottom-right handle to resize and the handle above it to rotate. You can also type exact values.
Press Copy JSON.
In the theme editor, paste into the block's Advanced JSON setting.

Switching colorway while you work is safe: the numbers stay put, because they describe the product rather than the picture. That is the whole job for most products.

Because the block lives on the product template, every product using that template shares the alignment. Give each hat style its own template and you set up thirty styles thirty times, not 2,400 photos at a time.

When some photos differ

Back views, detail crops and lifestyle shots are the exception. Rather than aligning them one by one, describe them:

Type a distinctive phrase into Applies to that appears in those photos' alt text or file names — back view, for instance. Matching is by substring, so avoid broad words that may also describe a front photo, such as "mesh back."
The panel tells you how many photos it caught, so you can check the word before relying on it.
Either tick No patch on these photos, or position the patch for them.

One rule covers every matching photo in the store, so back view is set once and applies to every rear shot you have.

The copied value looks like this:

{
  "alignment": {
    "default": { "x": 49.5, "y": 46.5, "width": 37, "rotation": 0 },
    "rules": [
      { "match": "back view", "hide": true },
      { "match": "three-quarter", "x": 44, "rotation": -6 }
    ]
  }
}

Rules are checked in order and the first match wins, so put the specific ones first. A rule only states what it changes; everything else comes from default, which means re-sizing the patch later carries through to the rules too.

Alt text is worth filling in for this reason — it is editable in bulk from the Shopify admin, and unlike a media id it survives re-uploading an image. If your photos have no alt text, the file name is matched instead. #2 matches the second photo in the gallery, and #id:1234567890 an exact Shopify media id.

Until you paste the JSON back into the theme editor, this only lasts for the session — a reload starts again from the saved values.

The editor never loads for normal visitors. It is only fetched when the query parameter is present.

Customers can fine-tune the whole patch with the Patch position on product sliders. Those controls start at zero and apply relative X, Y and size offsets over the alignment selected from Advanced JSON or custom.patch_config. Reset returns to the merchant placement, and media-specific rules remain active as the customer moves between product photos.

5. Per-product overrides (optional)

To vary configuration by product without adding a block per product, create a JSON product metafield with namespace and key custom.patch_config. Its contents are merged over the block settings and win any conflict.

{
  "shapes": ["shield", "circle"],
  "defaultShape": "shield",
  "allowTwoTone": false,
  "defaults": { "primaryMaterial": "black-pebble", "engravingColor": "gold" },
  "alignment": {
    "default": { "x": 50, "y": 44, "width": 38, "rotation": 0 }
  }
}

This is the place for the one style that hangs differently from the rest of the template, and it is bulk-editable from a CSV export, so correcting a family of products does not mean opening each one.

Order of precedence, later winning: material set → block settings → Advanced JSON → product metafield.

6. What reaches the order

Visible on the cart, checkout and order:

Patch Shape, Patch Material
Patch Color — only when several sets are offered. Patch Material then names the set, matching how these read on a production sheet: Premium Leatherette, Buckskin. With a single set there is nothing to name, so the color goes on Patch Material and Patch Color is left off.
Patch Artwork Method (Engraved or Full color UV print)
Patch Engraving Color, Patch Die Cut, Patch Design
Artwork — the customer's uploaded file
Patch Mockup — a 1200px product-photo placement PNG, if enabled and the selected material supports preview

Hidden from the customer but kept on the order:

_Patch Config — compact JSON with the exact selections, artwork position, scale and rotation
_Patch Vector — the SVG version, if enabled

For a non-preview material, generated PNG/SVG properties are omitted. The original uploaded artwork or selected design reference, shape, material group, selected group swatch, and _Patch Config still reach the order.

The property prefix (Patch) and the artwork property name are both settings, so they can match your existing naming.

7. Working with the design gallery

The configurator reads the existing design picker rather than replacing it.

If a design is already selected when the product page loads, it is used as the artwork automatically.
Selecting or clearing a design anywhere on the page updates the preview live.
Designs work in both engraved and full color modes.
Turn Hide upload with design on if a customer should not be able to do both at once.

No changes to the design gallery are required.

Troubleshooting

The block says the product is not set up for live preview. No materials were found. Check that Material sets has at least one entry selected and that the set holds at least one patch_material with a texture image or fallback color.

The set picker is missing even though several sets are selected. The picker only appears once every offered material carries a set. A set that resolved to nothing — empty, or every material missing both an image and a fallback color — leaves the rest ungrouped, and the block falls back to showing one flat list.

Swatches show flat colors instead of texture. The texture image is missing from the metaobject entry, or the image failed to load. The fallback color is used so the configurator keeps working.

The preview is not on the product photo. Check the Gallery selector setting matches your gallery element, and that the block is inside Buy buttons on a product page.

The patch is missing from a photo it should be on. A placement rule matched it. Rules match anywhere in the alt text or file name, so a broad word catches more than intended — back also matches "backcountry". Make the word more specific, or move the rule below the one that should win.

The patch is in the wrong place on one style. Every product on a template shares its alignment. Either give that style its own product template, or set alignment.default on its custom.patch_config metafield, which overrides the block for that product alone.

An uploaded shape does not appear. Shapes are traced in the browser after the rest of the configurator loads, so they arrive a moment late. If one never arrives, the reason is logged to the browser console: usually the entry has no file, or the file is not a readable SVG. Re-export it as plain SVG rather than "SVG with editor data".

An uploaded shape comes out hollow or the wrong outline. The file is drawn with strokes rather than fills, so the trace follows the centre of each line. Convert the strokes to outlines and export again.

Contour says the artwork could not be traced. The artwork is blank, or it is a flat photo with no clear subject. Contour works best with a PNG that has a transparent background.

The Contour outline misses part of the artwork. The trace keeps every region of the file, so separate elements and outer rings are included; only specks smaller than 2% of the largest region are dropped. If something is still being ignored it is probably fainter than the alpha cutoff — raise Contour border to pull the outline further out, or lower the dieCut.threshold value in the advanced JSON so softer edges register.

Contour corners look rounded. Turns sharper than 32 degrees are drawn square and everything gentler is curved, which keeps a diamond pointed while a circle stays smooth. Artwork with a soft outer edge can read as a gentle turn; set dieCut.cornerAngle lower in the advanced JSON to treat more of the outline as corners.

The mockup did not reach the order. The designer now finishes and verifies the current mockup before adding the item to cart. If generation fails, the item stays on the product page and shows an error instead of submitting incomplete production files. Check that material textures and gallery design images are available with CORS from the storefront.

A non-preview material still shows an old mockup. Switching material groups clears both generated file inputs immediately. If an old file remains in a test cart, remove the earlier cart line and add the newly configured product again.

Accelerated checkout buttons are hidden while the Patch designer is active. Customers must use Add to cart so artwork validation and the generated files finish before Shopify receives the line item.

Media gallery

Click-to-zoom is turned off automatically whenever the Patch designer is active for the product (including nested under Buy buttons). Zoom and artwork drag share the product photo, so leaving both on makes placement unreliable. The live-preview template also has Enable zoom unchecked as a fallback.