import { EkoGallery } from '@ekolabs/eko-gallery-react';

<EkoGallery 
    className="mb-4"
    config={config}
    variantId={variantId}
    activeItemIndex={activeItemIndex}
    onEvent={onEkoGalleryEvent}
>
    {/* Your existing product gallery component that will serve as a fallback */}
    <CustomerGalley />
</EkoGallery>

This component accepts the following props:

Prop	Type	Description
className	String	Optional. class names to add to the `EkoGallery` component, for styling purposes for example.
config	Object	The eko gallery configuration. This object will be published via the eko platform and exposed via an api endpoint (see below).
variantId	String	Optional. The selected variant (if applicable). It is used to switch to the relevant variant gallery assets when the product variant changes.
activeItemIndex	Number	Optional. Updates the displayed item of the EkoGallery.
onEvent	Function	Optional. Handler for events occurred in the eko gallery, for third party tools tracking for example.

When passing the onEvent prop, make sure to use the useCallback() hook to avoid unnecessary re-renders.

Config data fetching

To get the eko product configs, you should use the getEkoProductConfigUrl() function to get the url, fetch the data and pass it to the EkoGallery component.

The getEkoProductConfigUrl() receives the eko sales channel id and returns the url to fetch the eko product configs from.

import { getEkoProductConfigUrl } from '@ekolabs/eko-gallery-react';

const EKO_SALES_CHANNEL_ID = process.env.EKO_SALES_CHANNEL_ID;

const ekoProductConfigUrl = getEkoProductConfigUrl(EKO_SALES_CHANNEL_ID);
const ekoProductResponse = await fetch(ekoProductConfigUrl).then(res => res.json());
const ekoProductConfigs = ekoProductResponse.data;

Analytics setup

Our 1st party tracking tool should be added in order to track events on the site.

The eko analytics snippet

The eko analytics snippet should be added to the site's head tag, here is an example in Next.js:

// _document.tsx

import Script from 'next/script';
import { getEkoAnalyticsSnippet } from '@ekolabs/eko-gallery-react';

const IS_PRODUCTION = process.env.NODE_ENV === 'production';

render() {
    return (
        <Html lang="en">
            <Head>
                <Script id="eko-analytics-snippet" strategy="beforeInteractive">
                    {getEkoAnalyticsSnippet(IS_PRODUCTION)}
                </Script>
            </Head>
            <body>
                <Main />
                <NextScript />
            </body>
        </Html>
    );
}

Events

The eko gallery dispatches events through the onEvent handler. Use this to track user interactions and gallery lifecycle events.

Event Types

Event	Description
`galleryinit`	Fired when the gallery component initializes
`gallerycoverdisplayed`	Fired when the cover image (first carousel item) loads
`galleryloaded`	Fired when the interactive smart gallery is fully loaded
`activeitemindexchanged`	Fired when the active gallery item changes
`interaction`	Fired on user interactions (clicks, scrolls, buttons, etc.)
`swipe`	Fired when the user swipes within the interactive video

Event Payloads

`activeitemindexchanged` event

Fired when the displayed gallery item changes (via thumbnail click, carousel scroll, or internal navigation).

Property	Type	Description
`index`	Number	The zero-based index of the newly active item

`interaction` event

Property	Type	Description
`elementid`	String	A unique identifier of the element that was interacted with
`interactiontype`	String	The type of interaction (`click`, `wheel`, `swipe`)
`elementtype`	String	The type of element (e.g., `start`, `next button`, `choice button`)
`elementname`	String	A textual representation of the element

Common elementid values from the gallery:

thumbnail-{index} - Thumbnail navigation item clicked
nav - Navigation strip scrolled
carousel - Main carousel scrolled
eko-nav-arrow-prev / eko-nav-arrow-next - Navigation arrows clicked

`swipe` event

Fired when the user swipes within the interactive video.

Lifecycle events (`galleryinit`, `gallerycoverdisplayed`, `galleryloaded`)

These events are fired without a payload and indicate gallery state transitions.

Example

const onEkoGalleryEvent = useCallback((event, data) => {
    switch (event) {
        case 'galleryinit':
            console.log('Gallery initialized');
            break;
        case 'gallerycoverdisplayed':
            console.log('Cover image loaded');
            break;
        case 'galleryloaded':
            console.log('Interactive gallery ready');
            break;
        case 'activeitemindexchanged':
            console.log(`Active item changed to index: ${data.index}`);
            break;
        case 'interaction':
            console.log(`Interaction: ${data.elementid} (${data.interactiontype})`);
            break;
        case 'swipe':
            console.log('User swiped in interactive video', data);
            break;
    }
}, []);

ekoWebPixel

The ekoWebPixel API is used to track the events on your site.

Init once via the init() method:

import { ekoWebPixel } from '@ekolabs/eko-gallery-react';

const IS_PRODUCTION = process.env.NODE_ENV === 'production';

useEffect(() => {
    ekoWebPixel.init(IS_PRODUCTION);
}, []);

Track events via the track() method:

import { ekoWebPixel } from '@ekolabs/eko-gallery-react';

ekoWebPixel.track('pixel.page_viewed');
ekoWebPixel.track('pixel.product_viewed', { ... });
ekoWebPixel.track('pixel.cart.add', { ... });
ekoWebPixel.track('pixel.cart.remove', { ... });

// For traffic allocation:
ekoWebPixel.track('trafficallocation.decision', { ... });

// For non shopify backend stores:
ekoWebPixel.track('pixel.checkout', { ... });
ekoWebPixel.track('pixel.order', { ... });

Report on route changes:

import { ekoWebPixel } from '@ekolabs/eko-gallery-react';

ekoWebPixel.onRouteChanged();

Keywords

eko

eko-gallery

FAQs

What is @ekolabs/eko-gallery-react?

Is @ekolabs/eko-gallery-react popular?

Is @ekolabs/eko-gallery-react well maintained?

Package last updated on 19 Feb 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@ekolabs/eko-gallery-react

Eko Gallery React

Installation

Usage

EkoGallery Component

Config data fetching

Analytics setup

The eko analytics snippet

Events

Event Types

Event Payloads

activeitemindexchanged event

interaction event

swipe event

Lifecycle events (galleryinit, gallerycoverdisplayed, galleryloaded)