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

# Backgrounds

> Add backgrounds to your screenshots

## Backgrounds

Add custom backgrounds behind your screenshots for a polished, professional look. Perfect for social media, presentations, or marketing materials.

## Available backgrounds

DomShot provides several gradient presets:

| Background        | ID              | CSS Value                          |
| ----------------- | --------------- | ---------------------------------- |
| **Sunset**        | `sunset`        | Orange to coral gradient           |
| **Ocean**         | `ocean`         | Blue to purple gradient            |
| **Forest**        | `forest`        | Dark green to light green gradient |
| **Purple Haze**   | `purple-haze`   | Purple to deep violet gradient     |
| **Midnight**      | `midnight`      | Dark multi-tone gradient           |
| **Candy**         | `candy`         | Pink to rose gradient              |
| **Skyline**       | `skyline`       | Blue to white gradient             |
| **Autumn**        | `autumn`        | Orange to magenta gradient         |
| **Ocean Blue**    | `ocean-blue`    | Solid blue                         |
| **Vibrant Red**   | `vibrant-red`   | Solid red                          |
| **Forest Green**  | `forest-green`  | Solid green                        |
| **Sunset Orange** | `sunset-orange` | Solid orange                       |
| **Royal Purple**  | `royal-purple`  | Solid purple                       |
| **Hot Pink**      | `hot-pink`      | Solid pink                         |
| **Indigo**        | `indigo`        | Solid indigo                       |
| **Teal**          | `teal`          | Solid teal                         |

View all presets in the [Dashboard Playground](https://domshot.dev/dashboard?tab=playground) or create your own in [Dashboard Backgrounds](https://domshot.dev/dashboard?tab=backgrounds).

## Basic background

<CodeGroup dropdown>
  ```bash bash theme={null}
  curl "https://api.domshot.com/shot?key=YOUR_API_KEY&url=https://example.com&background=sunset" \
    --output screenshot.png
  ```

  ```typescript typescript theme={null}
  const params = new URLSearchParams({
    key: 'YOUR_API_KEY',
    url: 'https://example.com',
    background: 'sunset'
  });

  await fetch(`https://api.domshot.com/shot?${params}`)
    .then(res => res.blob())
    .then(blob => fs.writeFile('screenshot.png', blob));
  ```

  ```php php theme={null}
  $params = [
    'key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'background' => 'sunset'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.domshot.com/shot?' . http_build_query($params));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
  $result = curl_exec($ch);
  file_put_contents('screenshot.png', $result);
  curl_close($ch);
  ```

  ```go go theme={null}
  package main

  import (
      "net/http"
      "net/url"
  )

  func main() {
      params := url.Values{}
      params.Set("key", "YOUR_API_KEY")
      params.Set("url", "https://example.com")
      params.Set("background", "sunset")

      resp, _ := http.Get("https://api.domshot.com/shot?" + params.Encode())
      defer resp.Body.Close()

      // Save response to file
  }
  ```
</CodeGroup>

## Custom padding and border radius

<CodeGroup dropdown>
  ```bash bash theme={null}
  curl "https://api.domshot.com/shot?key=YOUR_API_KEY&url=https://example.com&background=sunset&backgroundPadding=60&backgroundBorderRadius=24" \
    --output screenshot.png
  ```

  ```typescript typescript theme={null}
  const params = new URLSearchParams({
    key: 'YOUR_API_KEY',
    url: 'https://example.com',
    background: 'sunset',
    backgroundPadding: '60',
    backgroundBorderRadius: '24'
  });

  await fetch(`https://api.domshot.com/shot?${params}`)
    .then(res => res.blob())
    .then(blob => fs.writeFile('screenshot.png', blob));
  ```

  ```php php theme={null}
  $params = [
    'key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'background' => 'sunset',
    'backgroundPadding' => '60',
    'backgroundBorderRadius' => '24'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.domshot.com/shot?' . http_build_query($params));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
  $result = curl_exec($ch);
  file_put_contents('screenshot.png', $result);
  curl_close($ch);
  ```

  ```go go theme={null}
  package main

  import (
      "net/http"
      "net/url"
  )

  func main() {
      params := url.Values{}
      params.Set("key", "YOUR_API_KEY")
      params.Set("url", "https://example.com")
      params.Set("background", "sunset")
      params.Set("backgroundPadding", "60")
      params.Set("backgroundBorderRadius", "24")

      resp, _ := http.Get("https://api.domshot.com/shot?" + params.Encode())
      defer resp.Body.Close()

      // Save response to file
  }
  ```
</CodeGroup>

<Tip>
  The `backgroundPadding` parameter accepts pixel values. If not specified, it defaults to 5% of the viewport's minimum dimension.
</Tip>

## With mobile viewport

<CodeGroup dropdown>
  ```bash bash theme={null}
  curl "https://api.domshot.com/shot?key=YOUR_API_KEY&url=https://example.com&background=sunset&viewportType=mobile" \
    --output mobile-preview.png
  ```

  ```typescript typescript theme={null}
  const params = new URLSearchParams({
    key: 'YOUR_API_KEY',
    url: 'https://example.com',
    background: 'sunset',
    viewportType: 'mobile'
  });

  await fetch(`https://api.domshot.com/shot?${params}`)
    .then(res => res.blob())
    .then(blob => fs.writeFile('mobile-preview.png', blob));
  ```

  ```php php theme={null}
  $params = [
    'key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'background' => 'sunset',
    'viewportType' => 'mobile'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.domshot.com/shot?' . http_build_query($params));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
  $result = curl_exec($ch);
  file_put_contents('mobile-preview.png', $result);
  curl_close($ch);
  ```

  ```go go theme={null}
  package main

  import (
      "net/http"
      "net/url"
  )

  func main() {
      params := url.Values{}
      params.Set("key", "YOUR_API_KEY")
      params.Set("url", "https://example.com")
      params.Set("background", "sunset")
      params.Set("viewportType", "mobile")

      resp, _ := http.Get("https://api.domshot.com/shot?" + params.Encode())
      defer resp.Body.Close()

      // Save response to file
  }
  ```
</CodeGroup>

## How it works

When you specify a `background`, DomShot:

1. Captures the screenshot at your specified viewport
2. Creates a canvas with the background color/gradient
3. Places your screenshot in the center with specified padding
4. Applies border radius and shadow effects
5. Returns the composite image

## Parameters

| Parameter                | Type   | Default                      | Description                                          |
| ------------------------ | ------ | ---------------------------- | ---------------------------------------------------- |
| `background`             | string | -                            | Background ID from table above or custom backgrounds |
| `backgroundPadding`      | number | 5% of min viewport dimension | Padding around screenshot in pixels                  |
| `backgroundBorderRadius` | number | `16`                         | Corner radius in pixels                              |

<Tip>
  Backgrounds add extra canvas size. Calculate final dimensions as:
  **Final size = Viewport size + (padding × 2)**
</Tip>

## Finding background IDs

Preset background IDs are listed in the table above. For custom backgrounds:

1. Go to [Dashboard Backgrounds](https://domshot.dev/dashboard?tab=backgrounds)
2. Click on your background to view details
3. Copy the background ID

<Warning>
  Backgrounds are scoped to your organization. You can only use backgrounds that belong to your organization or the system presets.
</Warning>

## See also

* [Viewport Presets](/guides/screenshots/viewports) - Device sizes and dimensions
* [Image Formats](/guides/screenshots/formats) - PNG, JPEG, WebP options