NAV Navigation
Examples
x
Landing image that shows people working with an API to create a rocket ship
Shutterstock UI

Current version: 0.1.35

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.

Getting started

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:

  1. Go to https://shutterstock.com/account/developers/apps.
  2. Create or edit an app you want to use with the widget.
  3. In the Referrer field, specify a comma-separated list of host names that you will host the widget on.
  4. Make sure that each referrer host name is also listed in the Callback URL field.
  5. 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.35/static/css/sstk-widget.css">
<script src="https://api-cdn.shutterstock.com/0.1.35/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.

Generating the widget code

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:

Wizard that generates widget code

Embedding the widget on a page

Example: Embedding the widget on a page

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="https://api-cdn.shutterstock.com/0.1.35/static/css/sstk-widget.css">
    <script src="https://api-cdn.shutterstock.com/0.1.35/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.

  1. 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.

  2. Create an HTML element to contain the widget and give it an ID, such as widget-container.

  3. 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.

  4. In the the widget parameters, specify your API application's consumer key and the ID of the HTML element.

  5. 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:

Search widget

Running the widget locally

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

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:

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 the example in the right-hand pane.

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:

The right-hand column shows an example.

Handling errors

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);
}

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.

Searching

Users can search for media in the widget. 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.

Searching for media

Example: Searching for media

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

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.

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

Example: Getting image suggestions based on text

const widget = new ShutterstockWidget({
  mediaType: 'images',
  container: document.getElementById('widget-container'),
  key: 'YOUR_API_APP_CONSUMER_KEY',
  searchSuggestions: {
    numberOfSuggestionRows: 3,
    enable: true,
    textProvider: textProvider,
  },
});

function textProvider() {
  // Text to use to provide recommendations
  return "Planting flowers is a great way to make springtime more beautiful."
}

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. See the example in the right-hand pane.

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.

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:

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

ShutterstockWidget

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.

new ShutterstockWidget(options)

Example: Creating a search widget

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="https://api-cdn.shutterstock.com/0.1.35/static/css/sstk-widget.css">
    <script src="https://api-cdn.shutterstock.com/0.1.35/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.keywordSafeSearch boolean Hide results with potentially unsafe keywords
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.license [String] Filter the media according to one or more license types; valid values are "commercial", "editorial"
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.safe boolean Enable or disable safe search
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
options.searchSuggestions Object Options for searchSuggestions to be used
options.defaultKeywords Object Default keywords to append to each query in an object of key-value pairs, where the key is a two-character language code and the value is a string of keywords; you can include AND, OR, or NOT in the string to create conditional searches

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

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.

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

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.

ParameterTypeDescription
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

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.

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

Types

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

FieldTypeDescription
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

OverlayAction

Example

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

Action that can be overlayed on top grid results

FieldTypeDescription
overlayAction.icon string Icon to display.
overlayAction.label string Icon label
overlayAction.onClick function onClick function callback

SearchSuggestionConfig

Example

const widget = new ShutterstockWidget({
  mediaType: 'images',
  container: document.getElementById('widget-container'),
  key: 'YOUR_API_APP_CONSUMER_KEY',
  searchSuggestions: {
    numberOfSuggestionRows: 3,
    enable: true,
    textProvider: textProvider,
  },
});

function textProvider() {
  // Text to use to provide recommendations
  return "Planting flowers is a great way to make springtime more beautiful."
}

Options for getting image suggestions from text

FieldTypeDescription
searchSuggestions.enable string Set to true to enable search suggestions
searchSuggestions.numberOfSuggestionRows number The number of rows of results to show
searchSuggestions.textProvider function A function that returns the text to use

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

FieldTypeDescription
description String The description of the video
height String 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 video from the API
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
Examples