Why do WooCommerce gallery instructions not match my product-page editor?

Identify the editor behind the product page

Start from the product page or template you are editing, not from the wording of a tutorial. Determine whether its product gallery is the classic gallery implementation or a block-based gallery. The editor’s available controls are evidence; do not assume that a control described in instructions must exist in your setup.

Record the exact behavior you are trying to change, such as image order, zoom, or lightbox. These are distinct questions, and support for zoom or lightbox depends on the implementation and theme.

1. Open a non-public test copy of the product or template and locate the gallery actually rendered in its editor.
2. Note whether the gallery is classic or block-based, and write down the controls shown for that gallery.
3. Compare those controls with the instructions. If the instructions name a control that is absent, stop following those steps and find guidance for the implementation you identified.

Separate the featured image from gallery items

In WooCommerce, the featured Product Image is already the first gallery item. When checking order or repeated images, account for that relationship before interpreting the page as having an extra gallery setting.

Removing an image assignment from a product is not the same as deleting the underlying shared Media Library file. For a test, change only the assignment on the test copy and leave the library asset intact.

1. Record the test product’s featured Product Image and gallery assignments before editing.
2. Make one reversible change to the test copy, then inspect the rendered product page to see whether the intended image or order changed.
3. If you only need to remove an image from this product, remove its product assignment; do not delete shared media as a troubleshooting shortcut.

Branch on the missing behavior

If the instructions describe a setting your editor does not show, treat the mismatch as an implementation mismatch first, not proof that the control is hidden or broken. Identify the gallery type and use instructions that match it.

If the gallery type matches but zoom or lightbox still differs, inspect the theme and the behavior on the rendered page. Support depends on the implementation and theme, so the presence of a setting in one environment does not establish that another environment supports it.

If the task involves video, check the current WooCommerce version and the actual editor controls before planning the change. Do not infer video support from instructions for another version or gallery implementation.

1. Missing control: pause the tutorial steps, confirm the gallery implementation, and switch to matching guidance.
2. Control exists but behavior differs: inspect the rendered test page and theme-specific behavior before changing media assignments.
3. Video is involved: verify current version and available controls; if support remains unclear, do not publish based on an assumption.

Illustrative exercise: verify image order

Illustrative exercise: define the fictional test product “Field Bottle” with the featured Product Image set to “Bottle front” and one gallery item set to “Bottle detail.” These two distinct asset values are defined before comparison; the featured image is the first gallery item.

On a non-public copy, compare the rendered order before and after changing only the gallery assignment. Pass if “Bottle front” remains first and “Bottle detail” appears in the intended subsequent position, with no unintended shared media deleted. Fail if the order is still unexplained, the expected control is absent, or the live product was changed during diagnosis. On failure, return to identifying the implementation rather than trying unrelated settings.

Accept only observed behavior

Keep the change only when the editor’s gallery implementation is identified, the relevant controls are present, and the rendered test page shows the intended result. Record the implementation, the control used, and the observed page behavior so future instructions can be matched to the same setup.

Do not treat a tutorial’s screenshot or a control label as proof that zoom, lightbox, or video works in your theme. Use the test page as evidence, and leave the live product unchanged until the specific acceptance condition is met.

Scope of the documentation

The official references below support tool behavior and feature boundaries. The test fixture, branching decisions and acceptance criteria are Itemlume editorial recommendations; citation does not imply endorsement. Illustrative sizes, names and timings are not your production specifications.