Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sindresorhus/wallpaper
Manage the desktop wallpaper
https://github.com/sindresorhus/wallpaper
desktop-wallpaper javascript linux macos nodejs wallpaper windows
Last synced: 3 days ago
JSON representation
Manage the desktop wallpaper
- Host: GitHub
- URL: https://github.com/sindresorhus/wallpaper
- Owner: sindresorhus
- License: mit
- Created: 2015-04-03T07:04:15.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2024-07-22T10:58:53.000Z (6 months ago)
- Last Synced: 2025-01-01T22:07:04.860Z (10 days ago)
- Topics: desktop-wallpaper, javascript, linux, macos, nodejs, wallpaper, windows
- Language: JavaScript
- Homepage:
- Size: 6.08 MB
- Stars: 1,056
- Watchers: 17
- Forks: 91
- Open Issues: 12
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
- awesome - sindresorhus/wallpaper - Manage the desktop wallpaper (JavaScript)
- awesome-nodejs-cn - wallpaper - 更换桌面壁纸 (包 / 命令行程序)
- awesome-github-star - wallpaper
- awesome-nodejs - wallpaper - Change the desktop wallpaper. (Packages / Command-line apps)
- awesome-node - wallpaper - Change the desktop wallpaper. (Packages / Command-line apps)
- awesome-nodejs-cn - wallpaper - 更改桌面墙纸. (目录 / 命令行应用)
- awesome-nodejs - wallpaper - Manage the desktop wallpaper - ★ 552 (Command-line apps)
- awesome-nodejs-cn - wallpaper - **star:1056** 更换桌面壁纸 (包 / 命令行程序)
README
# wallpaper
> Get or set the desktop wallpaper
Works on macOS 10.14.4+, Linux, and Windows 10+.
*Maintainer needed for the Linux part of the code. No new Linux-related changes will be accepted until someone with good Linux knowledge volunteers.*
## Install
```sh
npm install wallpaper
```
## Usage
```js
import {getWallpaper, setWallpaper} from 'wallpaper';
await setWallpaper('unicorn.jpg');
await getWallpaper();
//=> '/Users/sindresorhus/unicorn.jpg'
```
## API
### getWallpaper(options?)
Returns a `Promise` with the path of the current desktop wallpaper.
#### options
Type: `object`
##### screen *(macOS only)*
Type: `string | number`\
Values: `'all'`, `'main'`, or the index of a screen from `.screens()`\
Default: `'main'`
The screen to get the wallpaper from.
If you set `'all'` then `getWallpaper()` will return a `Promise`.
### setWallpaper(imagePath, options?)
Returns a `Promise`.
On macOS, it sets the wallpaper on the active space. There is no way to set it on all spaces.
#### imagePath
Type: `string`
The path to the image to set as the desktop wallpaper.
#### options
Type: `object`
##### screen *(macOS only)*
Type: `string | number`\
Values: `'all'`, `'main'`, or the index of a screen from `.screens()`
Default: `'all'`
The screen to set the wallpaper on.
*On Linux and Windows it's hard-coded to `'main'`.*
##### scale *(macOS & Windows)*
Type: `string`\
macOS Values: `'auto' | 'fill' | 'fit' | 'stretch' | 'center'`\
Windows Values: `'center' | 'stretch' | 'tile' | 'span' | 'fit' | 'fill'`\
Default macOS: `'auto'`\
Default Windows: `'span'`
Scaling method.
### setSolidColorWallpaper(color, options?) *(macOS only)*
Returns a `Promise`.
#### color
Type: `string`
The color to set as a RGB Hex value. For example, `000000` for black.
#### options
Type: `object`
##### screen
Type: `string | number`\
Values: `'all'`, `'main'`, or the index of a screen from `.screens()`
Default: `'all'`
The screen to set the wallpaper on.
```js
import {setSolidColorWallpaper} from 'wallpaper';
await setSolidColorWallpaper('000000');
```
### screens() *(macOS only)*
Returns a `Promise` with the available screens.
```js
import {screens} from 'wallpaper';
await screens();
//=> ['Color LCD']
```
## FAQ
#### How can I set a website as a static wallpaper?
If you only need a static snapshot of the website, you can use [`capture-website`](https://github.com/sindresorhus/capture-website) and then pass the result to this package. You can make it semi-dynamic, by capturing the website snapshot every 10 seconds, for example.
#### How can I set a website, video, or WebGL as a dynamic wallpaper?
You cannot use this package to set a dynamic wallpaper.
On macOS, check out [Plash](https://github.com/sindresorhus/Plash), which lets you set any website as your wallpaper. The website could contain a fullscreen video, WebGL, slideshow, animated, etc.
You can also do this with Electron on macOS and Linux by using [`new BrowserWindow({type: 'desktop'})`](https://www.electronjs.org/docs/latest/api/browser-window#new-browserwindowoptions).
On Windows, you can use [Wallpaper Engine](https://wallpaperengine.io). It's available on Steam, HumbleBundle, and Green Man Gaming for around 4 USD.
## Related
- [wallpaper-cli](https://github.com/sindresorhus/wallpaper-cli) - CLI for this module
- [macos-wallpaper](https://github.com/sindresorhus/macos-wallpaper) - macOS binary used in this module
- [windows-wallpaper](https://github.com/sindresorhus/windows-wallpaper) - Windows binary used in this module
- [trash](https://github.com/sindresorhus/trash) - Move files and directories to the trash