
Current version: 0.1.34
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:
- 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.34/static/css/sstk-widget.css">
<script src="https://api-cdn.shutterstock.com/0.1.34/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:
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.34/static/css/sstk-widget.css">
<script src="https://api-cdn.shutterstock.com/0.1.34/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, specifyimages
orvideos
. 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:
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:
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 theresults
array in theonSearch
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 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:
header
: An object with classes for the header's container, subtitle, and title:container
,title
, andsubtitle
emptySearchResults
: An object with classes for the screen that shows when a search returns no results:container
,title
, andsubtitle
pagination
: An object with classes for the "Show more" button at the bottom of the results:container
andshowMore
searchBar
: An object with classes for the search bar:container
: The class for the container<div>
element for the search barformControlInput
: The class for the form<input>
elementinputGroup
: The class for the input group that contains the search query field and submit buttonsearchButton
: The class for the submit buttonsearchForm
: The class for the<form>
elementsearchIconContainer
: The class for the container for the submit buttonsearchIcon
: The class for the submit button
error
: Classes for the screen that shows when the API returns an error:container
,title
, andsubtitle
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.
category
: The ID or name of a Shutterstock-defined category; see GET /v2/images/categories in the API referencecontributor
: An array of contributor names or IDs to show images from those contributorscontributor_country
: An array of two character country codes to show images from contributors in those countriesimage_type
: An array of one or more image types, including "photo," "illustration," and "vector"keyword_safe_search
: Hide results with potentially unsafe keywordslanguage
: The two-character language code to interpret thequery
parameter in; see Localizing searches in the API referencelicense
: Filter the media according to one or more license types; valid values are "commercial", "editorial"orientation
: The orientation of the image, including "horizontal" and "vertical"page
: The page number of the resultspeople_number
: An integer number of people in the image, from 0 to 4per_page
: The number of results to show per pagequery
: One or more search terms separated by spaces; you can use NOT to filter out images that match a termsafe
: Enable or disable safe searchsort
: 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 referenceduration_from
: The minimum duration of the video in secondsduration_to
: The maximum duration of the video in secondskeyword_safe_search
: Hide results with potentially unsafe keywordslanguage
: The two-character language code to interpret thequery
parameter in; see Localizing searches in the API referencelicense
: Filter the media according to one or more license types; valid values are "commercial", "editorial"page
: The page number of the resultsper_page
: The number of results to show per pagequery
: One or more search terms separated by spaces; you can use NOT to filter out videos that match a termresolution
: The resolution of the video, including "4k," "standard_definition," and "high_definition"safe
: Enable or disable safe searchsort
: 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.
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:
numberOfSuggestionRows
: The number of rows of results to show.enable
: Whether to enable or disable the suggestions.textProvider
: A function that returns the text to use. You can use static text or retrieve text from somewhere else on the page.
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:
searchTerm
: The search query textsearchId
: The ID of the API searchtotal_results
: The number of resultsresults
: 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.
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.34/static/css/sstk-widget.css">
<script src="https://api-cdn.shutterstock.com/0.1.34/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.
Parameter | Type | Description |
---|---|---|
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.
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 |
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.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
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 |
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.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
Field | Type | Description |
---|---|---|
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
Field | Type | Description |
---|---|---|
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 |