DesktopOverlays

Getting Started ​

This page walks you from an empty folder to a working bundle that you can preview in the app and publish to the Steam Workshop.

What you need ​

  • A text editor.
  • Basic HTML, CSS, and JavaScript. A bundle is a small web page.
  • The DesktopOverlays app installed, so you can preview and publish.

No build tools are required. A single HTML file is enough to start. If you prefer a framework or a bundler, that works too, as long as the output is plain files the app can load.

Bundle folder layout ​

A bundle is a folder. The only required pieces are the manifest and the entry point it points to:

my-overlay/
  desktop-overlays.config.json   the manifest (required, must sit at the root)
  index.html                     the entry point
  thumb.png                      a thumbnail shown in the library and Workshop

You can add as many files and subfolders as you like (scripts, stylesheets, images, fonts, audio). See Assets and networking for how relative paths resolve.

Step 1: write the manifest ​

Create desktop-overlays.config.json. This is the smallest manifest that runs:

json
{
  "name": "Hello Overlay",
  "version": "1.0.0",
  "author": "your-name",
  "thumbnail": "thumb.png",
  "permissions": [
    { "scope": "sdk.options", "reason": "Reads the text and color you set" }
  ],
  "content": [
    { "name": "main", "entrypoint": "index.html", "type": "overlay", "width": 320, "height": 120 }
  ],
  "options": [
    { "key": "text", "name": "Text", "type": "input", "kind": "string", "default": "Hello" },
    { "key": "color", "name": "Color", "type": "input", "kind": "color", "default": "#ff8800" }
  ]
}

Three blocks do most of the work:

  • permissions lists the capabilities you want. The user approves them at install time. See Permissions.
  • content lists the surfaces the bundle can show. Most bundles have one.
  • options defines the controls in the settings panel. See Options.

The full field list is in the Manifest reference.

Step 2: write the entry point ​

Create index.html. Read the user's options through window.DesktopOverlaysAPI and update the page when they change:

html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <style>
      html, body { margin: 0; height: 100%; display: grid; place-items: center;
        font-family: 'Segoe UI', system-ui, sans-serif; }
      #label { font-size: 28px; font-weight: 700; }
    </style>
  </head>
  <body>
    <div id="label">Hello</div>
    <script>
      const api = window.DesktopOverlaysAPI
      const label = document.getElementById('label')

      function apply(opts) {
        label.textContent = opts.text ?? 'Hello'
        label.style.color = opts.color ?? '#ff8800'
      }

      // Read the current values once on load.
      api.options.get().then(apply)

      // React when the user changes a control.
      api.options.onUpdate((e) => {
        if (e.action === 'value-change') apply(e.values)
      })
    </script>
  </body>
</html>

The page has no background of its own, so it floats transparently over the desktop. Paint a background only where you want one.

Step 3: turn on developer mode ​

Loading a bundle straight from a local folder is gated behind a setting. Open the app settings and turn on Developer mode. Until you do, there is no way to add a dev folder; the Bundles list only shows overlays you installed from the Workshop.

With developer mode on, a Load folder action appears in the Bundles list. Use it to register your bundle folder as a live overlay.

Step 4: preview in the app ​

Use Load folder and pick your bundle folder. The overlay is served straight from disk and hot-reloads whenever you change a file, so you can edit the HTML and see the result without re-importing. Change a value in the options panel and the overlay updates through options.onUpdate.

While previewing, confirm two things:

  • Every capability you use is listed in permissions. If a namespace is missing, the matching part of DesktopOverlaysAPI is undefined. See Permissions.
  • Any remote URL you fetch is covered by a network.* permission, otherwise the request is blocked. See Assets and networking.

Step 5: publish ​

When the bundle is ready, publish it to the Steam Workshop from inside the app. The app packages the folder and uploads it. To update later, publish again from the same folder and the existing Workshop item is updated in place.

See Packaging and publishing for the full flow, including the ignore field that keeps source files and build junk out of the published bundle.

Where to go next ​