Searching

Users can search for media on the widget's search page. The widget uses the Shutterstock API to return results, so the results in the widget may not be the same as the results for the same search on shutterstock.com.

If you set the parameter showSearchBar to true, the search page shows a search bar that users can use to search for media. No further code is required to allow simple searches. When a user types a query and clicks the search button or presses Enter, the widget uses the Shutterstock API to run the search and show the results.

To customize searches, you can use the search page's search() method, which runs a search in the Shutterstock API and shows the results in the widget. This example uses the widget to search for horizontal photos of two people:

widget.getPage('mySearchPage').search({
  query: document.getElementById('query').value,
  image_type: 'photo',
  orientation: 'horizontal',
  people_number: 2,
  license: ['commercial', 'editorial'],
});

For image searches, you can use the following search parameters. For more information about these search parameters, see the GET /v2/images/search endpoint in the API reference. The parameters work the same way in the widget as they do when you use the API directly.

For video searches, you can use the following search parameters. For more information about these search parameters, see the GET /v2/videos/search endpoint in the API reference.

The search method also accepts the title parameter which sets the title of the widget if the dynamicTitle parameter is set to true. See the parameters for the widget constructor.

Getting search suggestions

The widget can provide suggestions based on English text that you provide through a function. The function can return complete sentences or individual keywords up to 100,000 characters. Here is an example:

{
  searchSuggestions: {
    numberOfSuggestionRows: 3,
    enable: true,
    textProvider: () => {
      // Text to use to provide recommendations
      return "Planting flowers is a great way to make springtime more beautiful.";
    },
  },
};

To set up search suggestions, add the searchSuggestions object to the widget. This object has these fields:

When you provide text for search suggestions, the widget adds a "View recommendations" button above the usual search results. Users can click this button to see the suggestion results.

Using reverse image search

The widget provides a page that uses Shutterstock's computer vision search to provide images that are similar to an image that you or the page user specifies.

To set up reverse image search, create an object of the type ShutterstockWidget.components.ReverseImageSearchPage, specify the properties for the page, and add it to the widget's pages array.

To allow users to upload images to use in reverse image search, set the page's props.dragDropTitle, props.dropTitle, and props.ctaTitle parameters to set the text for the reverse image search UI. The page automatically shows the results when the user uploads an image.

To control which image the page uses, encode the image in base 64 and set the resulting string as the value of the props.base64Image parameter. The page automatically shows the search results for that image.

For more information about computer vision search, including its limitations, see Computer vision search in the Shutterstock API reference.

Here is an example:

const myReverseImageSearchPage = {
  name: 'myReverseImageSearchPage',
  component: ShutterstockWidget.components.ReverseImageSearchPage,
  props: {
    onItemClick: (e, item) => {
      e.preventDefault();
      widget.navigateTo('myImageDetailsPage', {
        item,
      });
    },
    showMore: true,
    title: 'Reverse image search',
    ctaTitle: 'Upload image',
    dragDropTitle: 'Drag and drop an image to find similar images',
    dropTitle: 'Drop the image here to find similar images',
  }
};

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

widget.render();

Responding to searches

When the API returns the search results, the widget shows the assets. You can trigger custom behavior with the onSearch callback. This callback receives an object that has these fields:

This example uses the onSearch callback to log information about the results in the browser console:

const mySearchPage = {
  name: 'mySearchPage',
  component: ShutterstockWidget.components.SearchPage,
  props: {
    mediaType: 'images',
    onSearch,
    subtitle: 'Search page',
    title: 'Shutterstock UI',
  }
};

function onSearch({ searchTerm, searchId, total_results, results }) {
  console.log(`Your search for ${searchTerm} found ${total_results} results. The first result is "${results[0].description}"`);
}

Responding to clicks

By default, when a user clicks on an asset thumbnail on the search page, the web browser opens the shutterstock.com page for that asset.

To specify custom behavior when the user clicks on a thumbnail, you can use the onItemClick callback. This function receives two parameters:

The callback should start with the command event.preventDefault() to prevent the widget from sending the user to the shutterstock.com page, as in this example:

const mySearchPage = {
  name: 'mySearchPage',
  component: ShutterstockWidget.components.SearchPage,
  props: {
    mediaType: 'images',
    onItemClick,
    subtitle: 'Search page',
    title: 'Shutterstock UI',
  }
};

function onItemClick(e, item) {
  e.preventDefault();
  console.log(item.description);
}

Adding overlay actions

You can also add clickable icons to the search results and run actions when the user clicks them, such as showing information about the piece of media or going to a page to license and download it. These clickable icons have an onClick callback that works just like the onItemClick callback.

Set these actions in the widget's overlayActions array. This example adds an action that logs the image ID to the browser console and another that goes to a licensing page for the asset.

const overlayActions = [
  {
    label: 'Insert preview',
    icon: '/download-comp.svg',
    onClick: (e, item) => {
      e.preventDefault();
      console.log(`Inserting preview image:${item.id}`);
    }
  },
  {
    label: 'License',
    icon: '/shopping-cart.svg',
    onClick: (e, item) => {
      e.preventDefault();
      widget.navigateTo(`/license/images/${item.id}`, {
        item,
        name: 'myImageLicensingPage'
      });
    }
  },
];

const mySearchPage = {
  name: 'mySearchPage',
  component: ShutterstockWidget.components.SearchPage,
  props: {
    mediaType: 'images',
    overlayActions,
    subtitle: 'Search page',
    title: 'Shutterstock UI',
  }
};

Handling errors

To handle search errors, use the onError callback on the search page.

The error.message field contains a textual description of the error. For example, if you pass an invalid value for a parameter, the description is "Validation failed."

The error.errors array has more specific information about the error. In the case of an invalid parameter value, the array includes an object with the error code, the passed parameter value, and a message about how the parameter did not match an expected value.

const mySearchPage = {
  name: 'mySearchPage',
  component: ShutterstockWidget.components.SearchPage,
  props: {
    mediaType: 'images',
    onError,
    subtitle: 'Search page',
    title: 'Shutterstock UI',
  }
};

function onError(error) {
  console.error(error.message);
  console.error(error.errors);
}