PPS Image Zoom: settings reference

Updated November 10, 2026

Choose the gallery features in WooCommerce > Image Zoom before enabling the module. The plugin extends WooCommerce's native gallery; it does not replace every theme's product gallery.

Release in preparation. This reference is not confirmation of download or Pro purchase availability.

Where to configure it

Open WooCommerce > Image Zoom with manage_woocommerce and use Save Changes. The form checks a nonce and stores pps_iz_settings. The Free and Pro controls share this screen.

The initial form and unsaved runtime defaults differ: the four gallery-behavior checkboxes have no schema-level checked default, although runtime defaults them to true when absent. Explicitly choose the behavior you want on the first save. Saving Enable alone with the other boxes unchecked saves those other values as false.

Gallery features

Field Initial form / unsaved runtime Save and runtime effect Access
Enable (enabled) Unchecked / false Checkbox saves true/false. Enables this module's native-support setup and product-page assets. Free
Hover zoom (force_theme_support) Unchecked / true Checkbox. Adds wc-product-gallery-zoom support while enabled. Clearing it stops this plugin adding support; it does not remove support declared by the theme. Free
Lightbox (force_native_lightbox) Unchecked / true Checkbox. Adds native gallery lightbox theme support. Does not provide a separate custom lightbox engine. Free
Gallery slider (force_native_slider) Unchecked / true Checkbox. Adds native gallery slider theme support. The actual gallery must use WooCommerce's supported markup/scripts. Free
Calm mobile zoom (disable_mobile_zoom) Unchecked / true Checkbox. On window load, destroys hover zoom on existing gallery images if viewport width is at most 768 pixels or the browser exposes touch support. It does not remove lightbox support and does not re-evaluate on resize. Free
Active thumbnail border (active_thumb_border) #2563EB / #2563EB Hex color (#RGB or #RRGGBB); invalid/blank saves #2563EB and output validates again. Sets a 2px solid border and full opacity on the active native thumbnail. Free

The 1.0.2 implementation applies native supports immediately if the theme-setup hook has already run, otherwise registers on that hook. Enabled support registration is not a promise that a custom gallery will initialize WooCommerce's native features.

Layout and lightbox (Pro)

Paid fields are disabled and skipped on save without approved entitlement. Existing values are preserved in storage but do not execute through Free's asset path. Invalid select choices fall back to the listed default; invalid/blank colors use the default.

Field Default Choices and runtime effect Access
Thumbnails (thumbnail_layout) horizontal Below the image (theme default) / horizontal, or Vertical, left of the image / vertical_left. Vertical CSS uses an 80px thumbnail column with a 1rem gap and adjusts the gallery wrapper. It depends on the native gallery selectors. Approved Pro
Lightbox style (lightbox_ui_style) standard Standard, Immersive dark / immersive_dark, or Frosted glass / glassmorphism. Standard uses overlay alpha 0.9; immersive dark 0.97; frosted glass 0.6 plus a 10px background blur where the browser supports it. Approved Pro
Lightbox overlay (overlay_color) #000000 Hex color; Pro converts it to RGBA using the selected style's alpha. Styles the native PhotoSwipe background, not product images. Approved Pro
Lightbox icons (icons_color) #FFFFFF Hex color; affects native PhotoSwipe button text/SVG fill. Themes using other icon markup can differ. Approved Pro

The Pro callback rechecks entitlement, enabled state and product context before adding CSS through the Free asset hook. Free keeps the shared gallery integration, active border and mobile handler. There is no second selectable zoom engine or Pro zoom-style control; the localized inner_zoom value is fixed and does not expose alternate behavior.

There are no product-level override fields, shortcode attributes, repeaters or plugin CPT in this revision. No custom-CSS editor is rendered. Previously stored custom_css can still be sanitized and applied by the entitled Pro callback; it is not a new editable Free setting.

Save behavior and edition boundaries

Checkboxes save true/false; missing checkboxes become false. The handler starts with the stored option array and preserves locked paid fields. Text/select/color values are sanitized by type, and malformed non-scalar values are treated as missing rather than accepted as a field value. A saved blank is not generally a reset to the module defaults.

Pro requires the parent plugin and an add-on SDK premium-code decision returning literal true. Missing, malformed or denied state leaves paid fields locked and paid CSS inactive. Retained paid options or a forced display flag alone do not enable them. Freemius account/activation UI is separate from gallery rendering.

Troubleshooting

For a missing zoom/lightbox/slider, check Enable and the relevant first-save checkbox, then the theme's native WooCommerce gallery markup and scripts. This plugin cannot remove a competing gallery implementation. A theme may already declare support even with a checkbox cleared.

For unexpected mobile behavior, check both the 768px threshold and touch detection; a touch-capable desktop can take the mobile branch. If Pro styling is absent, check entitlement, the product-page asset hook and PhotoSwipe selectors. Clear page/style caches after saving. Native zoom images are no longer hidden by this plugin's stylesheet in 1.0.2.

Disable or roll back safely

Uncheck Enable and save, then reload the product page. That stops this module adding supports/assets on new requests; it does not revoke theme-provided support or undo changes made by another gallery plugin. Deactivating Pro removes its presentation extensions while the Free gallery behavior can remain. Record existing values before changing them and avoid uninstall as a rollback.

Services and data

The inspected gallery path uses local plugin assets, WooCommerce scripts and the configured product images. A remote image host still receives image requests. This is not an all-local data guarantee.

Freemius account, licensing and updater services are separate from gallery rendering. Verify paid licensing, expiry policy and delivery/updates separately, and check mobile rendering and theme compatibility on your installation.

Related documentation

Setup: https://propluginstack.com/docs/image-zoom-setup-reference/

Changelog: https://propluginstack.com/changelog/image-zoom-source-changelog/