> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenshotly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK

> Install and use the official screenshotly-js client library for Node.js applications.

The official `screenshotly-js` package provides a convenient interface for the Screenshotly API in Node.js.

## Installation

```bash theme={null}
npm install screenshotly-js
```

## Setup

```javascript theme={null}
const { Screenshotly } = require('screenshotly-js');

// Simple setup
const client = new Screenshotly('your-api-key-here');

// Advanced setup with options
const client = new Screenshotly({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.screenshotly.dev', // optional
  timeout: 60000 // optional, in milliseconds
});
```

<Warning>
  Store your API key in an environment variable, not in your source code:

  ```javascript theme={null}
  const client = new Screenshotly(process.env.SCREENSHOTLY_API_KEY);
  ```
</Warning>

## Capture a screenshot

```javascript theme={null}
const screenshot = await client.capture({
  url: 'https://example.com',
  viewport_width: 1280,
  viewport_height: 800,
  format: 'png'
});

if (screenshot.success) {
  console.log('Screenshot URL:', screenshot.data.imageUrl);
  console.log('Remaining credits:', screenshot.remainingCredits);
} else {
  console.error('Error:', screenshot.error);
}
```

### Capture options

| Parameter              | Type    | Default       | Description                                         |
| ---------------------- | ------- | ------------- | --------------------------------------------------- |
| `url`                  | string  | —             | URL to capture (required)                           |
| `name`                 | string  | —             | Optional name for the screenshot                    |
| `viewport_width`       | number  | 1280          | Viewport width in pixels (100–5000)                 |
| `viewport_height`      | number  | 1024          | Viewport height in pixels (100–5000)                |
| `full_page`            | boolean | false         | Capture the full scrollable page                    |
| `format`               | string  | `'png'`       | Output format: `'png'`, `'jpeg'`, `'webp'`, `'pdf'` |
| `image_quality`        | number  | 80            | Image quality for JPEG/WebP/PDF (0–100)             |
| `device_scale_factor`  | number  | 1             | Device pixel ratio (1–3, use 2 for retina)          |
| `viewport_mobile`      | boolean | false         | Emulate mobile device                               |
| `viewport_has_touch`   | boolean | false         | Enable touch events                                 |
| `viewport_landscape`   | boolean | false         | Landscape orientation                               |
| `wait_for_selector`    | string  | —             | CSS selector to wait for                            |
| `selector`             | string  | —             | CSS selector of element to capture                  |
| `delay`                | number  | 0             | Delay in ms before capture (0–10000)                |
| `timeout`              | number  | 60000         | Request timeout in ms (1000–90000)                  |
| `block_ads`            | boolean | false         | Block advertisements                                |
| `block_cookie_banners` | boolean | false         | Block cookie consent banners                        |
| `block_chats`          | boolean | false         | Block chat widgets                                  |
| `dark_mode`            | boolean | —             | Emulate dark color scheme                           |
| `response_type`        | string  | `'by_format'` | Response format: `'by_format'`, `'json'`, `'empty'` |

## Batch capture

Capture multiple URLs with shared settings (max 50 URLs per request):

```javascript theme={null}
const result = await client.captureBatch({
  urls: [
    'https://example.com',
    'https://google.com',
    'https://github.com'
  ],
  options: {
    format: 'png',
    viewport_width: 1280,
    viewport_height: 800,
    full_page: true
  }
});

if (result.success) {
  console.log(`Succeeded: ${result.succeededCount}, Failed: ${result.failedCount}`);
  console.log('Remaining credits:', result.remainingCredits);
}
```

## List screenshots

Retrieve your captured screenshots with pagination:

```javascript theme={null}
const screenshots = await client.getScreenshots(1, 10); // page 1, 10 per page
console.log('Screenshots:', screenshots.data);
```

## Get a screenshot by ID

```javascript theme={null}
const screenshot = await client.getScreenshot('67b8a1c2d3e4f5a6b7c8d9e0');
console.log('Status:', screenshot.data.status);
console.log('URL:', screenshot.data.imageUrl);
```

## Delete a screenshot

```javascript theme={null}
const result = await client.deleteScreenshot('67b8a1c2d3e4f5a6b7c8d9e0');
console.log('Deleted:', result.success);
```

## Error handling

```javascript theme={null}
try {
  const screenshot = await client.capture({
    url: 'https://example.com'
  });

  if (!screenshot.success) {
    console.error('Capture failed:', screenshot.error);
  }
} catch (error) {
  // Network errors, timeouts, etc.
  console.error('Request failed:', error.message);
}
```

## Using with ES modules

```javascript theme={null}
import { Screenshotly } from 'screenshotly-js';

const client = new Screenshotly(process.env.SCREENSHOTLY_API_KEY);
```