Skip to content

Background scripts

A wallpaper is a picture, a colour or a gradient. A background script can be anything a page can draw: an animated canvas, particles, a slow field of ASCII characters. It runs in a box that fills the screen, behind the cards and over the wallpaper if there is one, and the cards go to glass over it as they do over a wallpaper.

Put the script in the data folder, in backgrounds/, and name it in the config without .js:

appearance:
background: ascii-flow # data/backgrounds/ascii-flow.js

Valet serves it from its own address, so the page’s security policy allows it without loosening anything, and nothing is fetched from anywhere else.

The repository has one to start from, examples/backgrounds/ascii-flow.js: characters that drift in waves, in your accent colour.

Like a wallpaper, it can be one for light and one for dark, and a tab can have its own. none turns it off there:

appearance:
background: { light: paper, dark: ascii-flow }
backgrounds: { Media: none, Home: rain }

The wall display runs background, the same for every page.

A background script is a module whose default export Valet calls once, with the box to draw in and what it’s showing:

data/backgrounds/my-background.js
export default function mount(el, { theme, tab }) {
const canvas = document.createElement('canvas');
el.appendChild(canvas);
// ...draw, with requestAnimationFrame...
return {
update({ theme, tab }) { /* the theme or the tab changed */ },
destroy() { /* stop drawing and remove what you added */ },
};
}
  • el fills the screen and takes no clicks. Size what you draw to it, and watch it with a ResizeObserver.
  • theme is light or dark. The theme’s colours are the page’s CSS variables: getComputedStyle(document.documentElement).getPropertyValue('--primary').
  • tab is the tab on screen, or empty on the overview and the wall.
  • destroy is called when you go to a tab with another background or none, or the theme switches to one with another.

Every glass card blurs what’s behind it, so a background that changes every frame makes the browser redraw that blur every frame too. A few things keep it cheap:

  • Draw with requestAnimationFrame. The browser stops calling it while the tab is hidden.
  • Don’t draw more often than you need to. The example draws 24 times a second, which is plenty for something slow.
  • Mind the screen. A high-resolution screen has four times the pixels; capping the canvas at twice the page’s size, as the example does, is enough.
  • Paint again as soon as you resize. Resizing a canvas blanks it, and until your next frame whatever is behind it shows through. If you paint every pixel anyway, an opaque canvas (getContext('2d', { alpha: false })) means a missed frame shows your own colour, not the wallpaper. The box itself stays the size of the largest viewport, so a phone’s toolbars coming and going as you scroll don’t resize it.

A background script never runs with appearance.motion: reduced or none, or when the device asks for less motion. Then the wallpaper, or the page’s own colour, is all there is.

A background script runs on the page with the same reach as Valet’s own code, like a plugin’s visual. Only use one you wrote or have read. Only you can turn one on: the assistant can’t set background or backgrounds, and config check names a script that isn’t in the folder.