refresh date: 2026-09-25
robots: noindex

<br />

> [!NOTE]
> **Important:** This API works **only on ChromeOS**.

<br />

<br />

## Description

Use the `chrome.wallpaper` API to change the ChromeOS wallpaper.

<br />

<br />

## Permissions

`wallpaper`  

<br />

<br />

## Availability

Chrome 43+ ChromeOS only

<br />

## Manifest

You must declare the "wallpaper" permission in the app's [manifest](https://developer.chrome.com/docs/extensions/mv3/manifest) to use
the wallpaper API. For example:

    {
      "name": "My extension",
      ...
      "permissions": [
        "wallpaper"
      ],
      ...
    }

## Examples

For example, to set the wallpaper as the image at
`https://example.com/a_file.png`, you can call `chrome.wallpaper.setWallpaper`
this way:

    chrome.wallpaper.setWallpaper(
      {
        'url': 'https://example.com/a_file.jpg',
        'layout': 'CENTER_CROPPED',
        'filename': 'test_wallpaper'
      },
      function() {}
    );

<br />

## Types

### WallpaperLayout

Chrome 44+

The supported wallpaper layouts.

#### Enum

"STRETCH"   
"CENTER"   
"CENTER_CROPPED"   

<br />

## Methods

### setWallpaper()

Promise

```typescript
chrome.wallpaper.setWallpaper(
  details: object,
  callback?: function,
): Promise<ArrayBuffer | undefined>
```

Sets wallpaper to the image at *url* or *wallpaperData* with the specified *layout*

#### Parameters

- details object
  - data ArrayBuffer optional

    The jpeg or png encoded wallpaper image as an ArrayBuffer.
  - filename string

    The file name of the saved wallpaper.
  - layout [WallpaperLayout](https://developer.chrome.com/docs/extensions/mv2/reference/wallpaper#type-WallpaperLayout)

    The supported wallpaper layouts.
  - thumbnail boolean optional

    True if a 128x60 thumbnail should be generated. Layout and ratio are not supported yet.
  - url string optional

    The URL of the wallpaper to be set (can be relative).
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (thumbnail?: ArrayBuffer) => void
  ```

  <br />

  - thumbnail ArrayBuffer optional

    The jpeg encoded wallpaper thumbnail. It is generated by resizing the wallpaper to 128x60.

#### Returns

- Promise\<ArrayBuffer \| undefined\>
  Chrome 96+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

<br />