Pexels JavaScript Client

You can install the pexels package using either npm or yarn. This library acts as a wrapper around the Pexels API and is compatible with both Node.js and browser environments.

yarn add pexels

# or

npm install pexels --save

The library exports all its type definitions via the main entrypoint. You can import interfaces and types directly from the package to ensure type safety when working with Pexels API responses (such as Photo, Video, or Collection).

import type { Photo, Collection } from 'pexels';

To use the Pexels JavaScript library, import createClient from the package. This function is the primary entrypoint for creating a client instance used to interact with the Pexels API. You will typically need to provide your Pexels API key during initialization (refer to the createClient implementation or documentation for specific configuration requirements).

import { createClient } from 'pexels';

const client = createClient({ apiKey: 'YOUR_API_KEY' });

A Collection represents a curated group of media on Pexels, containing metadata about the collection's title, description, and the count of photos and videos it contains.

export interface Collection {
  id: string;
  title: string;
  description: string | null;
  private: boolean;
  media_count: number;
  photos_count: number;
  videos_count: number;
}

The Video interface represents a video asset. It includes details about the video duration, user information, and an array of video_files which specify different qualities (hd, sd, or hls) and formats.

// Example of a Video object structure
const video: Video = {
  id: 789,
  width: 1920,
  height: 1080,
  url: 'https://pexels.com/videos/789',
  image: 'https://images.pexels.com/videos/789/preview.jpg',
  full_res: undefined,
  tags: ['nature', 'forest'],
  duration: 15,
  user: {
    id: 101,
    name: 'Jane Smith',
    url: 'https://pexels.com/users/janesmith'
  },
  video_files: [
    {
      id: 1,
      quality: 'hd',
      file_type: 'string',
      width: 1920,
      height: 1080,
      link: 'https://link-to-video.mp4',
      fps: 30
    }
  ],
  video_pictures: [
    {
      id: 1,
      picture: 'https://link-to-image.jpg',
      nr: 1
    }
  ]
};

When making requests that return lists of media, you can use PaginationParams to control the results. This interface extends a general Params object and allows you to specify:

• per_page: The number of items to return per page.
• page: The specific page number to retrieve.

const params: PaginationParams = {
  per_page: 15,
  page: 2
};

The Photo interface represents a single image asset from Pexels. It includes metadata such as dimensions, URLs, and photographer information. The src property contains various image sizes for different use cases.

// Example of a Photo object structure
const photo: Photo = {
  id: 123,
  width: 1920,
  height: 1080,
  url: 'https://images.pexels.com/photos/123',
  alt: 'A beautiful landscape',
  avg_color: '#ffffff',
  photographer: 'John Doe',
  photographer_url: 'https://pexels.com/users/johndoe',
  photographer_id: 456,
  liked: false,
  src: {
    original: '...',
    large2x: '...',
    large: '...',
    medium: '...',
    small: '...', 
    portrait: '...', 
    landscape: '...', 
    tiny: '...'
  }
};

The VideoFilterParams interface allows you to refine video searches using dimension and duration constraints:

• min_width: Minimum width in pixels.
• max_width: Maximum width in pixels.
• min_duration: Minimum duration in seconds.
• max_duration: Maximum duration in seconds.

const videoFilters: VideoFilterParams = {
  min_width: 1280,
  max_duration: 60
};