Skip to content
Go to file


Failed to load latest commit information.


npm Travis

A server-side Javascript wrapper for working with the Unsplash API.

Before using the Unsplash API, you need to register as a developer and read the API Guidelines.

Quick start

Quick links to methods you're likely to care about:

Note: Every application must abide by the API Guidelines. Specifically, remember to hotlink images, attribute photographers, and trigger a download when appropriate.



$ npm i --save unsplash-js


This library depends on fetch to make requests to the Unsplash API. For environments that don't support fetch, you'll need to provide a polyfill.

// ES Modules syntax
import fetch from 'node-fetch';
global.fetch = fetch;

// require syntax
const fetch = require('node-fetch');
global.fetch = fetch;

Note: we recommend using a version of node-fetch higher than 2.4.0 to benefit from Brotli compression.


If you're using unsplash-js publicly in the browser, you'll need to proxy your requests through your server to sign the requests with the Access Key and/or Secret Key to abide by the API Guideline to keep keys confidential.

Creating an instance

To create an instance, simply provide an Object with your accessKey:

// ES Modules syntax
import Unsplash, { toJson } from 'unsplash-js';
// require syntax
const Unsplash = require('unsplash-js').default;
const toJson = require('unsplash-js').toJson;

const unsplash = new Unsplash({ accessKey: APP_ACCESS_KEY });

const unsplash = new Unsplash({
  accessKey: APP_ACCESS_KEY,
  // Optionally you can also configure a custom header to be sent with every request
  headers: {
    "X-Custom-Header": "foo"
  // Optionally if using a node-fetch polyfill or a version of fetch which supports the timeout option, you can configure the request timeout for all requests
  timeout: 500 // values set in ms

Credentials can be obtained from Unsplash Developers.

Error handling

  .catch(err => {
    // Your flawless error handling code

Instance Methods

All the instance methods below make use of the toJson helper method described below

You can’t perform that action at this time.