Customizing pages

The UI widget can show a variety of pages, such as this page that prompts the user to license an asset:

The UI widget can show these pages:

For detailed information about each page and its properties, see the Shutterstock UI reference.

To show a page in the widget, create an object of the page type, specify a name in its name property, and add it to the widget's pages array, as in the following example. You can theme and translate each page as described in Theming pages and Translating pages.

This example shows an example instance of the UI with an image search page and an image details page:

const mySearchPage = {
  name: 'mySearchPage',
  component: ShutterstockWidget.components.SearchPage,
  props: {
    editorialCountry: 'USA',
    languageCode: 'en',
    license: ['commercial'],
    mediaType: 'images',
    onItemClick: (e, item) => {
      e.preventDefault();
      widget.navigateTo('myImageDetailsPage', {
        item,
      });
    },
    showMore: true,
    showSearchBar: true,
    subtitle: 'Search page',
    title: 'Shutterstock UI',
  }
};

const myImageDetailsPage = {
  component: ShutterstockWidget.components.ImageDetailsPage,
  name: 'myImageDetailsPage',
  props: {
    showSearchBar: true,
    buttons: [
      {
        label: 'Insert preview',
        icon: '/download-comp.svg',
        onClick: (e, item) => {
          e.preventDefault();
          console.log(`Insert code to preview image ${item.id} here.`);
        },
      },
      {
        label: 'License',
        icon: '/shopping-cart.svg',
        onClick: (e, item) => {
          e.preventDefault();
          widget.navigateTo('myImageLicensingPage', {
            item,
            subscriptions, // Not shown in this example
          });
        },
      },
    ],
    subtitle: 'Details page',
    title: 'Shutterstock UI',
  },
};

const widget = new ShutterstockWidget({
  languageCode: 'en',
  title: 'Shutterstock UI',
  container: document.getElementById('widget-container'),
  key: '<YOUR_APP_CONSUMER_KEY_HERE>',
  pages: [
    mySearchPage,
    myImageDetailsPage,
    myImageLicensingPage, // Not shown in this example
  ],
});

widget.render();

Routing users to a page

onItemClick: (e, item) => {
  e.preventDefault();
  widget.navigateTo('myImageDetailsPage', {
    item,
  });
}

To send users to a page, use the function widget.navigateTo() and pass the name property of the page object. You can call this function as part of any callback or anywhere else in your code.

The widget.navigateTo() function accepts a props parameter that overrides the properties of the target page. For example, the handler function in the following example runs when a user clicks an image. This function receives information about the image that the user clicked in the item parameter. The function passes that information in the widget.navigateTo() function, which sends the user to the image details page and overrides that page's props.item property.

Search page

The asset search page is usually the landing page for the widget. Its properties include options such as what type of media to search for and default filters.

To set up a search page, create an object of the type ShutterstockWidget.components.SearchPage and specify the properties for the page. The following example creates a simple image search page. For a complete list of properties for this page, see the ShutterstockWidget.components.SearchPage page component in the Shutterstock UI reference.

For more information about setting up the search page and responding to user activity, see Searching.

const mySearchPage = {
  name: 'mySearchPage',
  component: ShutterstockWidget.components.SearchPage,
  props: {
    mediaType: 'images',
    onItemClick: (e, item) => {
      e.preventDefault();
      widget.navigateTo('myImageDetailsPage', {
        item,
      });
    },
    assetsPerPage: 4,
    showMore: true,
    showSearchBar: true,
    subtitle: 'Search page',
    title: 'Shutterstock UI',
  }
};


const widget = new ShutterstockWidget({
  languageCode: 'en',
  container: document.getElementById('widget-container'),
  key: 'YOUR_API_APP_CONSUMER_KEY',
  pages: [
    mySearchPage,
    myImageDetailsPage, // Not shown in this example
  ],
});

When the user searches for media, the widget stores the search results temporarily and makes those results available to other pages. When you send the user to a page and pass the asset ID, as in the command widget.navigateTo(), the new page automatically retrieves information about the asset from those search results.

To filter or manipulate the search results, you can access the result data in the onSearch callback's response.results parameter. Then you can override the results that a page has access to by sending it to the page's props.searchResults parameter.

Other pages

For information about setting up other pages, see the Shutterstock UI reference.

Theming pages

To override the CSS classes for the widget, pass an object with the new classes to the page object's theme parameter. This object sets classes for elements on the page, such as the header, pagination buttons, and search bar.

Each page has different classes that you can set. To see the classes for each page, see the theme parameter for the specific page.

Here is an example of custom classes for the search page:

{
  header: {
    container: 'containerCssClass',
    subtitle: 'subtitleCssClass',
    title: 'titleCssClass',
  },
  emptySearchResults: {
    container: 'containerCssClass ',
    subtitle: 'subtitleCssClass',
    title: 'titleCssClass',
  },
  pagination: {
    container: 'containerCssClass',
    showMore: 'showMoreCssClass',
  },
  searchBar: {
    container: 'themedContainer',
    formControlInput: 'themedFormControlInput',
    inputGroup: 'themedInputGroup',
    searchButton: 'themedSearchButton',
    searchForm: 'themedSearchForm',
    searchIconContainer: 'themedSearchIconContainer',
    searchIcon: 'themedSearchIcon',
  },
  error: {
    container: 'containerCssClass ',
    subtitle: 'subtitleCssClass',
    title: 'titleCssClass',
  },
}

Translating pages

The languageCode parameter sets the language for the widget. The widget provides translated UI text in these languages: