logo

Background

The most advanced background image extension for VSCode

rating installs downloads


Add multiple background images for the window, editors, sidebars, or the panel. Load backgrounds from file, glob, or URL. Transition between multiple background images.

editor background

📃 Installation

🖼️ Usage

  1. Type Background: Configuration in the command pallette or press the Background tab in the statusbar.
  2. Select where you want to add a background (Window, Editor, Sidebar, Panel).
  3. Add backgrounds and change how it should be displayed.
  4. Use Background: Install or press the install button.

✨ Features

🖼️ Multiple Backgrounds

Add background images for the whole window, editors, sidebars, or the panel. Transition between multiple background images.

Full Window
window background
Editor, Sidebar, and Terminal
editor background
Slideshow
multiple backgrounds

⚙️ Configuration Menu

Type Background: Configuration in the command pallette or press the Background tab in the statusbar to access the configuration menu.

configuration menu

✱ Glob, URL, and Environment Variable Support

Add background images by file, folder, glob, or URL.

⚠️ Use only / for directories

node-glob only accepts / as path separators, \ is reserved for escape characters.

file menu

💻 Commands

CommandDescription
Background: InstallInstalls and enables the background.
Background: UninstallUninstalls and disables the background.
Background: ReloadRandomizes the backgrounds. Background must already be installed.
Background: ConfigurationOpens the configuration menu.
Background: ChangelogOpens changelog.

⚙️ Configuration

Use the Background: Configuration command to access the configuration menu.

Background properties are saved as arrays so you can have different options for different UI elements.

The order settings are saved in is:

  1. Window
  2. Editor
  3. Sidebar
  4. Panel
BackgroundTypeDescription
background.windowBackgroundsstring[]The list of files or globs to use for the window background image.
background.editorBackgroundsstring[]The list of files or globs to use for editor background images.
background.sidebarBackgroundsstring[]The list of files or globs to use for the sidebar background images.
background.panelBackgroundsstring[]The list of files or globs to use for the panel background image.


PropertyTypeDescription
background.backgroundAlignmentenum[4]The alignment of the background image.
background.backgroundAlignmentValuestring[4]If the background image alignment is set to Manual, this is the literal value for the background-position css property. Only accepts a css <position>.
background.backgroundBlurstring[4]Background image blur. Only accepts a css <length>.
background.backgroundOpacitynumber[4]The UI opacity. 0 is fully visible and 1 is invisible.
background.backgroundRepeatenum[4]The background image repeat.
background.backgroundSizeenum[4]The background image size.
background.backgroundSizeValuestring[4]If the background image size is set to Manual, this is the literal value for the background-size css property. Only accepts a css <position>.
background.backgroundChangeTimenumber[4]How long in seconds before the background should automatically change. Set to 0 to always use the same image.


AdvancedTypeDescription
background.useWindowOptionsForAllBackgroundsbooleanIf enabled, all background images will use the options set for the windows background. This does not include the backgrounds, you still need to add background images separately.
background.renderContentAboveBackgroundbooleanIf enabled, content like images, PDFs, and markdown previews will render above the background.
background.smoothImageRenderingbooleanIf enabled, use smooth image rendering rather than pixelated rendering when resizing images.
background.CSSstringApply raw CSS to VSCode.

💻 Environment Variables

VariableDescription
${vscode:workspace}Current VSCode project folder
${user:home}Current user’s home directory
${...}System environment variable

⚠️ Known Issues

⚠️ (Mac) read-only file system

This extension doesn’t natively support Mac, please refer to #76 to get this extension working on Mac.

⚠️ (Linux) snap: read-only file system

Applications installed using snap are inherently read-only, install VSCode using deb or rpm.

⚠️ Doesn’t work on WSL

As described in #27, you can not change the background while running this extension in a remote WSL window. You can however still use custom backgrounds by installing and making changes in the main VSCode window, then opening a remote WSL window.

⚠️ VSCode stopped working

This extension modifies an internal file to make backgrounds work, if VSCode stops working replace %LocalAppData%\Programs\Microsoft VS Code\resources\app\out\vs\workbench\workbench.desktop.main.js with workbench.desktop.main-backup.js.

This extension also modifies %LocalAppData%\Programs\Microsoft VS Code\resources\app\product.json, replace with product-backup.json if VSCode stops working.

🔌 API

Add this extension to your package.json.

{
    ...
    "extensionDependencies": [
        "katsute.code-background"
    ]
    ...
}

Access the api by using:

const background = vscode.extensions.getExtension("katsute.code-background").exports;
  • install(): void

    Runs the Background: Install command.

  • uninstall(): void

    Runs the Background: Uninstall command.

  • reload(): void

    Runs the Background: Reload command.

  • get(ui): string[]?
    • ui : Background to get from; either window, editor, sidebar, panel.

    Returns an array of globs for the specified background.

  • add(ui, glob): Promise<boolean>
    • ui : Background to add to; either window, editor, sidebar, panel.
    • glob: Glob to add.

    Returns true if successful.

  • replace(ui, old, glob): Promise<boolean>
    • ui : Background to replace from; either window, editor, sidebar, panel.
    • old: Glob to replace.
    • glob: Updated glob.

    Returns true if successful.

  • remove(ui, glob): Promise<boolean>
    • ui : Background to remove from; either window, editor, sidebar, panel.
    • glob: Glob to remove.

    Returns true if successful.

 

GitHub CopilotOpen AIGitHub CopilotOpen AI

AI generated code is strictly prohibited on this repository.

This extension is released under the GNU General Public License (GPL) v2.0.

Development

Role
Developer & Maintainer
Started
June 2022
Completed
July 2022
Last Updated
September 2023
Description

The only background extension that supports glob. Add multiple background images for the window, editors, sidebars, or the panel. Created as an improved alternative to existing background extensions.

Status
Long Term Support

Built with
  • TypeScript
  • NodeJS
Built for
  • VSCode
Built using
  • VSCode