README.md

August 5, 2026 · View on GitHub

English | 中文 | 日本語

vscode-background

Bring background images to your Visual Studio Code

fullscreen, editor, sidebar, auxiliarybar, panel, carousel, custom images/styles...

GitHub | Visual Studio Marketplace

Multiple sections, editor, sidebar, auxiliarybar, panel

fullscreen

Installation

There are 2 ways to install this extension:

Install from Visual Studio Marketplace.
Search shalldie.background from vscode.

Custom

User defined requirements can be met by changing the configuration(settings.json).

what's settings.json | where?

Config

Global Config

Name	Type	Default	Description
`background.enabled`	`Boolean`	`true`	Whether to enable background extension.

Editor Section Config

Edit background.editor to config editor section.

Name	Type	Default	Description
`useFront`	`boolean`	`true`	Place the image above or below the code.
`style`	`object`	`{}`	Custom style for images. MDN Reference
`styles`	`object[]`	`[]`	Custom style for each image individually.
`images`	`string[]`	`[]`	Custom images, supports online and local images, as well as folders.
`interval`	`number`	`0`	Seconds of interval for carousel, default `0` to disabled.
`random`	`boolean`	`false`	Whether to randomly display images.

example:

{
  "background.editor": {
    "useFront": true,
    "style": {
      "background-position": "100% 100%",
      "background-size": "auto",
      "opacity": 0.6
    },
    "styles": [],
    // `images` supports online and local images, as well as folders.
    "images": [
      // online images, only `https` is allowed.
      "https://hostname/online.jpg",
      // local images
      "file:///local/path/img.jpeg",
      "/home/xie/downloads/img.gif",
      "C:/Users/xie/img.bmp",
      "D:\\downloads\\images\\img.webp",
      // `~` and environment variables are supported in local paths
      "~/Pictures/img.png",
      "${HOME}/Pictures/img.png",
      // local folders
      "/home/xie/images",
      // data URL
      "data:image/*;base64,<base64-data>"
    ],
    "interval": 0,
    "random": false
  }
}

Edit background.fullscreen, background.sidebar, background.auxiliarybar, background.panel to config these sections.

Name	Type	Default	Description
`images`	`string[]`	`[]`	Custom images, supports online and local images, as well as folders.
`opacity`	`number`	`0.1`	Opacity of the images, alias to opacity, `0.1 ~ 0.3` recommended.
`size`	`string`	`cover`	Alias to background-size, `cover` to self-adaption (recommended).
`position`	`string`	`center`	Alias to background-position, default `center`.
`styles`	`object[]`	`[]`	Custom style for each image individually.
`interval`	`number`	`0`	Seconds of interval for carousel, default `0` to disabled.
`random`	`boolean`	`false`	Whether to randomly display images.

example:

{
  "background.fullscreen": {
    // `images` supports online and local images, as well as folders.
    "images": [
      // online images, only `https` is allowed.
      "https://hostname/online.jpg",
      // local images
      "file:///local/path/img.jpeg",
      "/home/xie/downloads/img.gif",
      "C:/Users/xie/img.bmp",
      "D:\\downloads\\images\\img.webp",
      // `~` and environment variables are supported in local paths
      "~/Pictures/img.png",
      "${HOME}/Pictures/img.png",
      // local folders
      "/home/xie/images",
      // data URL
      "data:image/*;base64,<base64-data>"
    ],
    "opacity": 0.1,
    "size": "cover",
    "position": "center",
    "styles": [],
    "interval": 0,
    "random": false
  },
  // `sidebar` and `panel` have the same config as `fullscreen`
  "background.sidebar": {},
  "background.panel": {}
}