Image Library API

The image library option can be extend using a client side JavaScript API to integrate external image sources into the library.

External Library

The library checks for globally defined Javascript functions that it will call when the image library is navigated by the customer.

The following functions can be defined on the global window scope:

// called when a category is selected
clLibraryGetImages(category: string, page: number, size: number): Promise<ImagesResult>

// called when the library is searched
clLibrarySearchImages(query: string, page: number, size: number): Promise<ImagesResult>

// called when an image is selected - should return an img Url to be saved on the option
clLibraryGetImage(image: Image): String;

The objects returned have to be in the following format:

class Image {
 id?: string;   // Optional external image id.
 img: string;   // URL to the image.
 value: string; // Unique name of the image.
 text: string;  // Text shown on the image (if empty .value is used).
 price?: number; // Optional price of the image
}

class ImagesResult {
 total: number;    // Total number of images (used for paging).
 images: Image[];  // Array of images to show in this page.
}

Example

The following example integrates the free Pixabay API into the Image library:

const searchPixabay = (query, page, size) => {

    const key = 'YOUR_KEY';
    const api = 'https://pixabay.com/api/';

    return new Promise((resolve, reject) => {

        return fetch(`${api}?key=${key}&page=${page}&per_page=${size}&q=${query}`)
            .then(response => response.json())
            .then(response => {

                console.debug('pixabay response', response);

                let images = response.hits.map((hit) => {
                    return {
                        _hit: hit, // store hit for later access
                        id: String(hit.id),
                        value: String(hit.id),
                        text: hit.tags,
                        img: hit.webformatURL // use web format to show in list
                    };
                });

                resolve({total: response.totalHits, images: images });
            })
            .catch((error) => {
                reject(error);
            });

    });
};

window.clLibraryGetImage = (image) => {
    // when image is selected use the large image for the live preview
    return image._hit?.largeImageURL || image.img;
};

window.clLibraryGetImages = (category, page, size) => {
    // just search for the selected category value
    return searchPixabay(category.value, page, size);
};

window.clLibrarySearchImages = (query, page, size) => {
    // search with the provided query
    return searchPixabay(query, page, size);
};

Note: the code requires that you add your own API key.

Ensure that the code isn't placed within the product options configuration, as it will only render when the page loads. Instead, it should be loaded before the product page. To do this, navigate to App Settings -> Theme Settings -> JavaScript

Inside the product options, set up an image library and make sure to add a category. Choose a value for what you want to display in the library. This value will help search for images on Pixabay.

Single image

If you want to have a custom discovery mechanism on your store, and then directly link to a product detail page with a a pre selected image, you can use on of the following methods.

Variable / Metafield

You can set a Javascript variable in your theme that contains the image that should be loaded into the image library. The image URL can be dynamic, for example by reading a Metafield that is set on the product. You can provide the same object properties as in the image library functions above.

Example

{% if product.metafields.library.image != blank %} 
<script>
window.clLibraryImage = { 
   img: "{{ product.metafields.library.image.value }}",
   id: "1234",  
   text: "Dog", 
   price: 5 
};
</script>
{% endif %}

URL

You can also provide an image for the library via the URL. Use the following url parameters:

Note: only the library.img parameter is required.

Example

https://www.yourstore.com/product/custom-image?library.img=https://cdn.shopify.com/s/files/1/0245/2530/8009/files/a_ZZNs_rhaul-v-alva-491530-unsplash.jpg&library.text=Dog