RetroBar custom themes

#Install a theme, step by step

1. Open the custom themes folder

   RetroBar Properties › Advanced › Open custom themes folder. RetroBar creates the folder if it does not exist yet and opens it in File Explorer. The path is %LOCALAPPDATA%\RetroBar\ThemesCopy, usually C:\Users\you\AppData\Local\RetroBar\Themes.

2. Copy the .xaml file into it

   Only .xaml files directly in that folder count: RetroBar does not look in subfolders. If the theme came as a zip, take the .xaml out of it. The file name, without .xaml, becomes the theme's name in the list.

3. Pick it in Properties

   On the Taskbar tab, open the Theme list. While Properties is open, RetroBar watches the folder, so a file you copy in appears in the list straight away. Select it; the taskbar changes at once.

#Where RetroBar looks for themes

When you select a theme, RetroBar 1.22.122 tries three folders, in this order, and uses the first file with that name (from DictionaryManager.cs in the RetroBar source):

We confirmed the installed location on all three test machines: the installer puts RetroBar in C:\Users\you\AppData\Local\Programs\RetroBar, with Themes and Resources folders inside, unless you choose another folder during setup.

#What we tested, and what happened

We wrote ten test themes, selected each one with RetroBar 1.22.122 on Windows 11 (Arm64) and Windows Server 2025 and 2022, and recorded the taskbar, RetroBar's log and any error window. Tests A to F ran in two complete runs and G to J in one; every result was the same on all three machines. All test themes were in %LOCALAPPDATA%\RetroBar\Themes except G.

Full results, logs and the test themes: how we test and results.json (Windows 11 run).

#Why a downloaded theme loses its Start button, or crashes RetroBar

Most built-in themes load their pictures (the XP and Vista Start buttons, and the desktop preview in Properties) with paths such as ../Resources/startxpbluebutton.png. The path is relative to the theme file. From RetroBar's program folder, ../Resources is the program's own Resources folder, so it works. From %LOCALAPPDATA%\RetroBar\Themes, the same path points to %LOCALAPPDATA%\RetroBar\Resources, a folder that does not exist.

Many themes shared online are edited copies of a built-in theme and still carry those paths. With RetroBar 1.22.122 such a theme does not just lose its pictures: in our test C, RetroBar crashed as soon as it was selected. That matches recent reports in RetroBar's tracker (#1492, #1498).

Three fixes work, all confirmed in our tests:

1. Point the images at the installed RetroBar (best, works on any PC with RetroBar installed normally). In the theme file, replace every ../Resources/ with ../../Programs/RetroBar/Resources/ (test J). From %LOCALAPPDATA%\RetroBar\Themes, that path leads to the Resources folder of RetroBar installed in its default folder, for every user. Our Theme Checker can make this change for you.
2. Copy RetroBar's Resources folder next to your themes, to %LOCALAPPDATA%\RetroBar\Resources (test H). Themes that come with their own Resources folder ask you to do exactly this with theirs. Copy the program's images in too if the theme also uses RetroBar's own pictures.
3. Use full paths, such as C:/Users/you/AppData/Local/Programs/RetroBar/Resources/… (test D). It works, but only on your PC, because the path contains your user name.

UriSource="../Resources/startxpbluebutton.png"
UriSource="../../Programs/RetroBar/Resources/startxpbluebutton.png"

If you installed RetroBar into another folder, or use the portable version, fix 1 does not apply: use fix 2 or 3.

#Base a theme on a built-in one

Most custom themes only change a few things: a colour, a font, the clock. You do not need to copy a whole built-in theme for that. There are two ways:

• Only change colours and sizes of the classic look: write just the keys you want to change, with nothing inherited. RetroBar always loads its base theme (System.xaml) first and puts yours on top, so everything you do not set keeps the classic Windows look. That is test E.
• Change an XP, Vista or other look: inherit that theme with MergedDictionaries, then add your changes after it. The built-in themes inherit by file name (Source="Windows XP Blue.xaml"), but from the custom themes folder that file is not found (test A). Use a path that leads to the installed theme instead, ../../Programs/RetroBar/Themes/… (test I):

<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary Source="../../Programs/RetroBar/Themes/Windows XP Blue.xaml" />
    </ResourceDictionary.MergedDictionaries>
    <!-- Your changes, after the merge: they win -->
    <SolidColorBrush x:Key="ClockForeground" Color="#FFFFC0" />
</ResourceDictionary>

Inheriting this way also brings the built-in theme's images with it, because they are loaded relative to the built-in file, in the program folder. The path works for any user with RetroBar installed in its default folder, so you can share the file. With RetroBar installed elsewhere, use the full path of the theme file instead, such as C:/Users/you/AppData/Local/Programs/RetroBar/Themes/Windows XP Blue.xaml (test B).

#Make your own theme

A theme is a WPF resource dictionary: a list of named values (brushes, sizes, fonts, images and styles) that RetroBar looks up by name. To make one:

1. Start from the smallest file that works

   Copy the example above (or test E's three colours) into a new file in the custom themes folder, for example My Theme.xaml.

2. Change one key at a time

   Find the part you want to change in the key reference below, add that key to your file, save, and check the result.

3. See your change

   RetroBar reads the file when you select the theme. After saving, pick another theme in Properties and then yours again.

4. Check it

   Paste the file into the Theme Checker. It flags typos in key names, keys RetroBar no longer reads, wrong types, and paths that will break on other PCs.

Every built-in theme builds on another. This is the family tree in 1.22.122; to see how a built-in theme does something, open its file from the program's Themes folder:

#Theme Checker

Paste a theme or drop the .xaml file here. It is checked in your browser against the 307 keys RetroBar 1.22.122 reads; nothing is uploaded.

#All 307 theme keys

Every key that RetroBar's built-in themes set in 1.22.122, grouped by the part of the taskbar it changes, with its type and the first release that had it. A key you set in your theme replaces the same key from the theme you inherit and from the base theme.

#Questions

Found something out of date or wrong? Tell us at hello@retrobar.dev and we will fix it.