Landing image that shows people working with an API to create a rocket ship

Shutterstock UI

Current version: 0.1.29

This page always shows reference documentation for the most recent version of the Shutterstock UI search widget. You can bookmark this page for the most recent version, but in most cases, use the drop-down list at the left-hand side of the page to select a version and to go to the documentation for that specific version of the widget.

Overview

The Shutterstock UI search widget lets you embed Shutterstock image and video search on your site. You can customize actions to happen when users search or click items, and you can get information about what they search for and click.

Prerequisites

The widget works only with API applications that have referrer authentication enabled. In your application, you must specify the host names on which you will host the widget. You can specify localhost as a referrer for local testing.

To add referrer authentication to your app:

Go to https://shutterstock.com/account/developers/apps.
Create or edit an app you want to use with the widget.
In the Referrer field, specify a comma-separated list of host names that you will host the widget on.
Make sure that each referrer host name is also listed in the Callback URL field.
Save the app and note the consumer key.

Now you can use the consumer key from your application to authenticate your instance of the widget.

Quick start

Widget source code

<link rel="stylesheet" type="text/css" href="https://api-cdn.shutterstock.com/0.1.29/static/css/sstk-widget.css">
<script src="https://api-cdn.shutterstock.com/0.1.29/static/js/sstk-widget.js"></script>

To put the widget on your page, get the widget source code from the links in the right-hand pane. Then, create and use an instance of the widget as in the examples later in this documentation.

You can use the wizard on this page to generate a starter widget with the settings and parameters that you choose:

https://tech.shutterstock.com/shutterstock-ui-wizard/

This page lets you edit the widget code in a live preview so you can set it up the way you want it:

Example: Embedding the widget on a page

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="https://api-cdn.shutterstock.com/0.1.29/static/css/sstk-widget.css">
    <script src="https://api-cdn.shutterstock.com/0.1.29/static/js/sstk-widget.js"></script>

    <script>
      window.onload = () => {
        const widget = new ShutterstockWidget({
          mediaType: 'images',
          container: document.getElementById('widget-container'),
          key: 'YOUR_API_APP_CONSUMER_KEY',
          showSearchBar: true,
          onItemClick: (event, item) => {
            event.preventDefault();
            document.getElementById('statusText').innerHTML = `You clicked ${item.description}`;
          },
          onSearch: (search) => {
            document.getElementById('statusText').innerHTML = `Your search found ${search.total_results} results. The first result is "${search.results[0].description}"`;
          },
        });

        widget.search({
          query: 'thunder storm',
        });
      }
    </script>
  </head>
  <body>
    <p id="statusText"></p>
    <div id="widget-container"></div>
  </body>
</html>

To add the widget to a page, import its source files and pass parameters that specify where to place it on the page. For an example, see the right-hand column.

On the page, import the JavaScript and CSS files.

In most cases, use the wizard to get links to a specific version of the CSS and JS files. If you link to these specific versions, the widget stays on that version until you choose to upgrade.
Create an HTML element to contain the widget and give it an ID, such as widget-container.
Create the the widget object and then call its search() method to render it when the page loads. Without search results, it does not load on the page.
In the the widget parameters, specify your API application's consumer key and the ID of the HTML element.
In the mediaType parameter, specify images or videos. The widget can show only one type of media at a time.

Now the widget appears on the page. You can implement the onError, onItemClick, and onSearch callbacks to respond to actions as described below.

For information on all of the parameters that the widget accepts, see new ShutterstockWidget(options).

The search widget looks like this with the search bar enabled:

For information on running the widget locally with Node.js, see Shutterstock UI on the Shutterstock developer portal.

Searching for media

Example: Searching for media

widget.search({
  query: document.getElementById('query').value,
  image_type: 'photo',
  orientation: 'horizontal',
  people_number: 2,
});

If you set the parameter showSearchBar to true, the widget 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() method, which runs a search in the Shutterstock API and shows the results in the widget. The example in the right-hand column uses the widget to search for horizontal photos of two people.

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.

category: The ID or name of a Shutterstock-defined category; see GET /v2/images/categories in the API reference
contributor: An array of contributor names or IDs to show images from those contributors
contributor_country: An array of two character country codes to show images from contributors in those countries
image_type: An array of one or more image types, including "photo," "illustration," and "vector"
language: The two-character language code to interpret the query parameter in; see Localizing searches in the API reference
orientation: The orientation of the image, including "horizontal" and "vertical"
page: The page number of the results
people_number: An integer number of people in the image, from 0 to 4
per_page: The number of results to show per page
query: One or more search terms separated by spaces; you can use NOT to filter out images that match a term
sort: The sort order: "newest," "popular" (the default), "relevance", or "random"

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.

aspect_ratio: The aspect ratio of the video, including "4_3," "16_9," and "nonstandard"
category: The ID or name of a Shutterstock-defined category; see GET /v2/videos/categories in the API reference
duration_from: The minimum duration of the video in seconds
duration_to: The maximum duration of the video in seconds
language: The two-character language code to interpret the query parameter in; see Localizing searches in the API reference
page: The page number of the results
per_page: The number of results to show per page
query: One or more search terms separated by spaces; you can use NOT to filter out videos that match a term
resolution: The resolution of the video, including "4k," "standard_definition," and "high_definition"
sort: The sort order: "newest," "popular" (the default), "relevance", or "random"

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.

Responding to searches

Example: Responding to search results

const widget = new ShutterstockWidget({
  mediaType: 'images',
  container: document.getElementById('widget-container'),
  key: 'YOUR_API_APP_CONSUMER_KEY',
  onSearch: onSearch,
});

function onSearch({ searchTerm, searchId, total_results, results }) {
  document.getElementById('statusText').innerHTML = 
  `Your search for ${searchTerm} found ${total_results} results.
  The first result is "${results[0].description}"`;
}

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

searchTerm: The search query text
searchId: The ID of the API search
total_results: The number of results
results: The array of search results. For information about the search results, see ImageResult and VideoResult.

The example in the right-hand column uses the onSearch callback function to show information about the results in an element on the page.

Responding to clicks

Example: Responding to click events

const widget = new ShutterstockWidget({
  mediaType: 'images',
  container: document.getElementById('widget-container'),
  key: 'YOUR_API_APP_CONSUMER_KEY',
  onItemClick: onItemClick,
});

function onItemClick(event, item) {
  event.preventDefault();
  alert(item.description);
}

By default, when a user clicks on an asset thumbnail, 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 function. This function receives two parameters:

event: The JavaScript event object that represents the click event.
item: An object with information about the asset that the user clicked, with the same fields as elements in the results array in the onSearch callback function.

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

Theming

Example: Assigning custom classes

{
  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',
  }
}

To override the CSS classes for the widget, pass an object with the new classes to the theme parameter. This object sets classes for the header, pagination buttons, search bar, error component, and the screen that shows an empty search result.

The object has these fields:

header: An object with classes for the header's container, subtitle, and title: container, title, and subtitle
emptySearchResults: An object with classes for the screen that shows when a search returns no results: container, title, and subtitle
pagination: An object with classes for the "Show more" button at the bottom of the results: container and showMore
searchBar: An object with classes for the search bar:
- container: The class for the container <div> element for the search bar
- formControlInput: The class for the form <input> element
- inputGroup: The class for the input group that contains the search query field and submit button
- searchButton: The class for the submit button
- searchForm: The class for the <form> element
- searchIconContainer: The class for the container for the submit button
- searchIcon: The class for the submit button
error: Classes for the screen that shows when the API returns an error: container, title, and subtitle

The right-hand column shows an example.

Handling errors

Example: Handling errors

widget-onError.js

To handle API errors, use the onError callback function.

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.

ShutterstockWidget

ShutterstockWidget

new ShutterstockWidget(options)

Example: Creating a search widget

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="https://api-cdn.shutterstock.com/0.1.29/static/css/sstk-widget.css">
    <script src="https://api-cdn.shutterstock.com/0.1.29/static/js/sstk-widget.js"></script>

    <script>
      window.onload = () => {
        const widget = new ShutterstockWidget({
          mediaType: 'images',
          container: document.getElementById('widget-container'),
          key: 'YOUR_API_APP_CONSUMER_KEY',
          showSearchBar: true,
          onItemClick: (event, item) => {
            event.preventDefault();
            document.getElementById('statusText').innerHTML = `You clicked ${item.description}`;
          },
          onSearch: (search) => {
            document.getElementById('statusText').innerHTML = `Your search found ${search.total_results} results. The first result is "${search.results[0].description}"`;
          },
        });

        widget.search({
          query: 'thunder storm',
        });
      }
    </script>
  </head>
  <body>
    <p id="statusText"></p>
    <div id="widget-container"></div>
  </body>
</html>

Create a widget with the specified options.

Param	Type	Description
options	`Object`	An object with the options for the widget
options.assetsPerPage	`Number`	Number of assets to display on the page; the default is 26
options.container	`HtmlElement`	(required) A valid HtmlElement to render the widget in
options.contributor	`String`	Show assets with the specified contributor names or IDs
options.customTranslations	`Object`	Can be used to supply additional translations; see the Translations section
options.dynamicSubtitle	`Boolean`	If `true`, placeholders such as `{{TOTAL_COUNT}}` and `{{SEARCH_TERM}}` can be passed in the subtitle; the widget replaces them with the total number of results and the search query
options.dynamicTitle	`Boolean`	If `true`, the widget updates its title to match either the search query or the value of the title parameter that you pass to the search() method
options.emptyResultsSubtitle	`String`	Custom subtitle that overrides the EmptySearchResults component subtitle
options.emptyResultsTitle	`String`	Custom title that overrides the EmptySearchResults component title; you can include the placeholder `{{SEARCH_TERM}}` in the title; the widget replaces it with the search query.
options.imageType	[`String`]	The type of image, such as photo, illustration, or vector; by default, all image types are returned
options.key	`String`	(required) Your Shutterstock public API consumer key
options.languageCode	`String`	2-letter ISO 3166-1 alpha-2 country code such as DE or US (the default); the widget uses this country code to translate the total count of results
options.mediaType	`String`	(required) The type of media to show in the widget: `image` or `video` or 'editorial'
options.onError	`onError`	A callback function to run when the API search or widget returns errors; see Handling errors
options.onItemClick	`onItemClick`	A callback function to run when the user clicks on an asset in the widget
options.onSearch	`onSearch`	A callback function to run after the search has returned results
options.showItemId	`Boolean`	If set to true, the widget shows the asset ID when the users hovers over an asset in the results
options.showMoreButtonText	`String`	Text for the pagination button; the default is "Show more"
options.showSearchBar	`Boolean`	Whether to show a search bar as part of the widget; the default is false
options.subtitle	`String`	Subtitle of the widget
options.theme	`Object`	An object that specifies CSS classes; see Theming
options.title	`String`	Title of the widget
options.overlayActions	[`OverlayAction`]	A list of OverlayAction
options.customHeaders	`Object`	Custom headers to augment requests with; get sent to public api
options.searchFilters	`Object`	Options for searchFilters to be used

shutterstockWidget.mediaType

Reset search results if the user changes the media type between videos, images, and editorial So that previous search result doesn't appear.

shutterstockWidget.search(rawSearchParams)

Example: Running a search

widget.search({
  query: document.getElementById('query').value,
  image_type: 'photo',
  orientation: 'horizontal',
});

Run a search and show the results in the widget.

Param	Type	Description
rawSearchParams	`Object`	An object with search parameters

Callbacks

onSearch

Example: Responding to search results

const widget = new ShutterstockWidget({
  mediaType: 'images',
  container: document.getElementById('widget-container'),
  key: 'YOUR_API_APP_CONSUMER_KEY',
  onSearch: onSearch,
});

function onSearch({ searchTerm, searchId, total_results, results }) {
  document.getElementById('statusText').innerHTML = 
  `Your search for ${searchTerm} found ${total_results} results.
  The first result is "${results[0].description}"`;
}

The function that runs when the widget runs a search.

Parameter	Type	Description
response	`Object`	An object with information about the search and its results
response.searchTerm	`String`	The search query text
response.searchId	`Number`	The ID of the API search
response.total_results	`Number`	The number of results
response.results	[`ImageResult`] \| [`VideoResult`]	The array of search results

onItemClick

Example: Responding to clicks

const widget = new ShutterstockWidget({
  mediaType: 'images',
  container: document.getElementById('widget-container'),
  key: 'YOUR_API_APP_CONSUMER_KEY',
  onItemClick: onItemClick,
});

function onItemClick(event, item) {
  event.preventDefault();
  alert(item.description);
}

The function that runs when a user clicks an image or video.

Parameter	Type	Description
event	`Object`	The JavaScript event object that represents the click event
item	`Object`	An object with information about the asset that the user clicked, with the same fields as elements in the results array in the onSearch callback function

onError

Example: Handling errors

const widget = new ShutterstockWidget({
  mediaType: 'images',
  container: document.getElementById('widget-container'),
  key: 'YOUR_API_APP_CONSUMER_KEY',
  onError: onError,
});

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

The function that runs when the widget throws an error.

Parameter	Type	Description
error	`Object`	Information about one or more errors
error.message	`String`	A textual description of the error
error.errors	[`Object`]	An array of more specific information about the error

Types

OverlayAction

Example

{
  icon: '/icon.svg',
  label: 'Hello',
  onClick: (e, item) => {
    e.preventDefault();
    console.log(item);
  }
}

Action that can be overlayed on top grid results

Field	Type	Description
overlayAction.label	`string`	Icon label
overlayAction.icon	`string`	Icon to display.
overlayAction.onClick	`function`	onClick function callback

ImageResult

Example

{
  "id": "526400839",
  "aspect": 1.1102,
  "src": "https://image.shutterstock.com/display_pic_with_logo/164693082/526400839/stock-photo-light-blue-flower-on-a-white-background-isolated-with-clipping-path-closeup-big-shaggy-flower-526400839.jpg",
  "slug": "light blue flower on a white  background isolated  with clipping path. Closeup. big shaggy  flower. for design.  Dahlia.-526400839",
  "link": "",
  "description": "light blue flower on a white  background isolated  with clipping path. Closeup. big shaggy  flower. for design.  Dahlia.",
  "preview_1000": {
    "url": "https://ak.picdn.net/shutterstock/photos/526400839/watermark_1000/7f8d92d1e15dead16b940ee7a3e89777/preview_1000-526400839.jpg",
    "width": 1000,
    "height": 901
  },
  "preview_1500": {
    "url": "https://image.shutterstock.com/z/stock-photo-light-blue-flower-on-a-white-background-isolated-with-clipping-path-closeup-big-shaggy-flower-526400839.jpg",
    "width": 1500,
    "height": 1351
  },
  "height": 405,
  "url": "https://image.shutterstock.com/display_pic_with_logo/164693082/526400839/stock-photo-light-blue-flower-on-a-white-background-isolated-with-clipping-path-closeup-big-shaggy-flower-526400839.jpg",
  "width": 450
}

An image search result

Field	Type	Description
aspect	`Number`	The aspect ratio of the image in decimal format
description	`String`	The description of the image
height	`Number`	The height of the thumbnail in pixels
id	`String`	The ID of the asset; you can use this ID to get more information about the image from the API
link	`String`	A link to the image page on shutterstock.com
preview_1000	`String`	An object that contains the URL, width, and height of a preview image that is 1000 pixels on its larger dimension
preview_1500	`String`	An object that contains the URL, width, and height of a preview image that is 1500 pixels on its larger dimension
search_id	`Number`	The ID of the API search
slug	`String`	A unique string that identifies the image
src	`String`	A link to a thumbnail image
url	`String`	A link to a thumbnail image
width	`Number`	The width of the thumbnail in pixels

VideoResult

Example

{
  "id": "1054726028",
  "link": "",
  "slug": "Drone following a traditional Thai long tail boat in Crystal clear waters-1054726028",
  "description": "Drone following a traditional Thai long tail boat in Crystal clear waters",
  "preview": {
    "webm": "https://ak.picdn.net/shutterstock/videos/1054726028/preview/stock-footage-drone-following-a-traditional-thai-long-tail-boat-in-crystal-clear-waters.webm",
    "mp4": "https://ak.picdn.net/shutterstock/videos/1054726028/preview/stock-footage-drone-following-a-traditional-thai-long-tail-boat-in-crystal-clear-waters.mp4"
  },
  "width": 533.4,
  "height": 300,
  "src": "https://ak.picdn.net/shutterstock/videos/1054726028/thumb/1.jpg",
  "url": "https://ak.picdn.net/shutterstock/videos/1054726028/thumb/1.jpg"
}

A video search result

Field	Type	Description
description	`String`	The description of the video
id	`String`	The ID of the asset; you can use this ID to get more information about the video from the API
height	`String`	The height of the thumbnail in pixels
link	`String`	A link to the video page on shutterstock.com
preview	`String`	An object with links to preview videos in mp4 and webm format
search_id	`String`	The ID of the API search
slug	`String`	A unique string that identifies the video
src	`String`	A link to a thumbnail image
url	`String`	A link to a thumbnail image
width	`String`	The width of the thumbnail in pixels

Current version: 0.1.29

Overview

Prerequisites

Quick start

Generating the widget code

Embedding the widget on a page

Running the widget locally

Searching for media

Responding to searches

Responding to clicks

Theming

Handling errors

ShutterstockWidget

new ShutterstockWidget(options)

shutterstockWidget.mediaType

shutterstockWidget.search(rawSearchParams)

Callbacks

onSearch

onItemClick

onError

Types

OverlayAction

ImageResult

VideoResult