Tab Backgrounds

Wave's background system harnesses the full power of CSS backgrounds, letting you create rich visual effects through the "background" attribute. You can apply solid colors, gradients (both linear and radial), images, and even blend multiple elements together.

Managing Backgrounds

Custom backgrounds are stored in ~/.config/waveterm/backgrounds.json.

To edit using the UI:

1. Click the settings (gear) icon in the widget bar
2. Select "Settings" from the menu
3. Choose "Tab Backgrounds" from the settings sidebar

Or launch from the command line:

wsh editconfig backgrounds.json

File Format

Backgrounds follow this format:

{
  "bg@<key>": {
    "display:name": "<Background name>",
    "display:order": <number>,
    "bg": "<CSS background value>",
    "bg:opacity": <float>
  }
}

To see how Wave's built-in backgrounds are defined, check out the default backgrounds.json file.

Configuration Keys

Key Name	Type	Function
display:name	string	Name shown in the UI menu (required)
display:order	float	Controls the order in the menu (optional)
bg	string	CSS background attribute for the tab (supports colors, gradients, images, etc.)
bg:opacity	float	The opacity of the background (defaults to 0.5)
bg:blendmode	string	The blend mode of the background
bg:bordercolor	string	The color of the border when a block is not active (rarely used)
bg:activebordercolor	string	The color of the border when a block is active

Examples

Simple solid color:

{
  "bg@blue": {
    "display:name": "Blue",
    "bg": "blue",
    "bg:opacity": 0.3,
    "bg:activebordercolor": "rgba(0, 0, 255, 1.0)"
  }
}

Complex gradient:

{
  "bg@duskhorizon": {
    "display:name": "Dusk Horizon",
    "bg": "linear-gradient(0deg, rgba(128,0,0,1) 0%, rgba(204,85,0,0.7) 20%, rgba(255,140,0,0.6) 45%, rgba(160,90,160,0.5) 65%, rgba(60,60,120,1) 100%), radial-gradient(circle at 30% 30%, rgba(255,255,255,0.1), transparent 60%), radial-gradient(circle at 70% 70%, rgba(255,255,255,0.05), transparent 70%)",
    "bg:opacity": 0.9,
    "bg:blendmode": "overlay"
  }
}

Background image:

{
  "bg@ocean": {
    "display:name": "Ocean Scene",
    "bg": "url('/path/to/ocean.jpg') center/cover no-repeat",
    "bg:opacity": 0.2
  }
}

info

Background images support both URLs and local file paths. For better reliability, we recommend using local files. Local paths must be absolute or start with ~ (e.g., ~/Downloads/background.png). We support common web formats: PNG, JPEG/JPG, WebP, GIF, and SVG.

tip

The setbg command can help generate background JSON:

# Preview a solid color background
wsh setbg --print "#ff0000"
{
  "bg:*": true,
  "bg": "#ff0000",
  "bg:opacity": 0.5
}

# Preview a centered image background
wsh setbg --print --center --opacity 0.3 ~/logo.png
{
  "bg:*": true,
  "bg": "url('/absolute/path/to/logo.png') no-repeat center/auto",
  "bg:opacity": 0.3
}

Just add the required display:name field and a bg@<key> wrapper to complete your background entry!