This hook is called before previewing an image field on the detail page.

It performs additional business logic before image preview, including:

• Deciding whether preview is allowed based on the current record or field
• Preventing the host's default image preview

Parameters

functional registers the hook callback. The image preview parameters and common parameters are available on context.

Parameter	Description	Type	Allowed Values	Default
context	Image preview event context	Object	--	--
plugin	Current plugin runtime information; business logic normally does not need it	Object	--	--

context

Parameter	Description	Type	Allowed Values	Default
context.objectApiname	Legacy compatibility field for the current detail object API name	String	--	--
context.fieldName	Current image field API name	String	--	--
context.data	Parsed image object array for the current image field	Object[]	--	--
context.objectData	Complete parsed detail data for the current record; null when unavailable	Object | null	--	--
context.startIndex	Zero-based index of the clicked image in data	Number	--	--
context.field	Current image field describe	Object	--	--

The common context.objectApiName and legacy event field context.objectApiname currently have the same value. New code should use context.objectApiName; use objectApiname only for compatibility with existing plugin code.

Common optional properties of an item in context.data:

Parameter	Description	Type
smallUrl	Thumbnail URL	String
path	Image path	String
is_recapture	Whether the image was recaptured	Boolean
scene_error	Image scene error information	Any
describe_api_name	API name of the object owning the image	String

Return Value

The hook may return a result object or Promise<Object>. The host waits for the Promise to resolve before deciding whether to continue the default preview.

Parameter	Description	Type	Allowed Values	Default
stopPreView	Whether to prevent the host's default image preview	Boolean	--	false

Returning { stopPreView: true } prevents the default preview. Returning nothing, omitting stopPreView, or returning false continues it. Other returned fields do not replace preview images or the preview component.

A direct throw from a synchronous callback is caught and logged by the PWC adapter, after which the host continues the default preview. The current Detail wrapper does not handle a rejected Promise, including an exception thrown from an async callback, so the default preview will not open. Catch and report asynchronous failures inside the hook, then explicitly resolve either { stopPreView: false } or { stopPreView: true }.

Basic Examples

Prevent Preview Based on Image State

export default class Plugin {
    apply() {
        return [{
            event: 'detail.previewImage.before',
            functional: this.previewBefore.bind(this)
        }];
    }

    previewBefore(context, plugin) {
        const currentImage = context.data[context.startIndex];
        const shouldStop = Boolean(currentImage?.scene_error);

        return Promise.resolve({
            stopPreView: shouldStop
        });
    }
}

Read Current Image Information

export default class Plugin {
    apply() {
        return [{
            event: 'detail.previewImage.before',
            functional: this.previewBefore.bind(this)
        }];
    }

    previewBefore(context, plugin) {
        const currentImage = context.data[context.startIndex];
        if (currentImage) {
            console.log(context.fieldName, currentImage.path);
        }
        return Promise.resolve({ stopPreView: false });
    }
}

Notes

1. Return stopPreView: true to cancel the default preview. Do not use a throw or rejected Promise for normal cancellation.

2. Handle asynchronous failures inside the hook so an uncaught exception does not interrupt preview unexpectedly.

3. objectData is a read result for the current detail data. Do not mutate it to update the detail page.