Customize Frontend
Zaparoo Frontend can switch color schemes, show a background image, replace the top bar logo, and load your own system artwork, Hub icons, and system display names without rebuilding Frontend.
Image and name customization is read at startup. Restart Frontend after adding, changing, or removing custom files.
Color scheme
Open Settings > Appearance > Color scheme to change the colors used across every screen. There are 19 presets: Zaparoo Dark, Zaparoo Light, and Classic Purple; editor and terminal palettes such as Nord, Dracula, Synthwave '84, Gruvbox, Everforest, Solarized Dark, Rosé Pine, and Oxocarbon; the light Flexoki Paper and Solarized Light; and retro sets like Amber Phosphor, Green Phosphor, Neo Geo, NES, Virtual Boy, and Game Boy. The change applies immediately.
The selection is stored in /media/fat/zaparoo/frontend.toml:
[settings]
color_scheme = "nord"
The picker shows a three-color swatch for each preset. In the file, the value is the preset name in lowercase with hyphens, such as nord, dracula, or amber-phosphor; an unknown value falls back to zaparoo-dark.
Presets recolor Frontend's built-in tinted artwork. Your own images and full-color logos are not changed.
Color intensity, on the same page, sets how strongly the accent color tints tile edges and selected rows. Subtle is the default and matches earlier releases; Vivid pushes the tint harder. It is stored next to the scheme:
[settings]
color_scheme = "nord"
color_intensity = "vivid"
Custom folder
On MiSTer, the default customization folder is:
/media/fat/zaparoo/custom/
Create one subfolder for each kind of image override:
/media/fat/zaparoo/custom/
systems/ # system artwork in the systems grid
hub/ # Hub category and action icons
To use another folder, edit /media/fat/zaparoo/frontend.toml:
[custom]
dir = "/media/usb/zaparoo-art"
Image filenames
Name each image after the ID it overrides. Matching is case-insensitive, so snes.png and SNES.png match the same system.
Supported image types are PNG, JPG, JPEG, WEBP, BMP, and SVG.
- Bitmap files must be 8 MiB or smaller, have no edge over 8192 pixels, and fit a 32 MiB decoding memory budget.
- SVG files must be 256 KiB or smaller and use self-contained vector artwork, without embedded or referenced images or SVG filters.
Invalid or oversized files fall back to built-in artwork. Resize the image or convert an unsupported SVG to PNG if your override is ignored.
System artwork
System artwork in systems/ uses Zaparoo system IDs:
systems/snes.png
systems/genesis.svg
systems/turbografx16.webp
Hub icons
Hub icons in hub/ use category or action IDs:
| ID | Hub item |
|---|---|
arcade | Arcade category |
computer | Computer category |
console | Console category |
handheld | Handheld category |
other | Other category |
resume | Resume |
favorites | Favorites |
liked | Liked |
playlater | Play later |
disliked | Disliked |
decks | Decks |
recents | Recently played |
topplayed | Top played |
search | Search |
update | Update |
settings | Settings |
hub/arcade.png
hub/favorites.svg
hub/settings.svg
To change one tile's icon from Frontend, open its options menu and choose Change tile icon..., under Edit tile for a game, deck, system, or Resume tile, then pick an image on the SD card, a USB drive, or a network share. The image stays where it is; Frontend saves its path. Use default icon, in the picker's Menu, goes back to the normal icon.
In frontend.toml, that is the icon value of the tile's [[hub.items]] entry. It takes either an absolute image path or a name, such as icon = "retro", that matches hub/retro.png in the custom folder. A tile's own icon wins over a hub/ file named after its ID.
Custom images are shown as-is. Built-in icons are tinted to match the color scheme, but your override images are not recolored.
System names
To rename systems in Frontend, add a [custom.system_names] table to /media/fat/zaparoo/frontend.toml:
[custom.system_names]
snes = "Super Nintendo"
psx = "PlayStation"
genesis = "Mega Drive"
The key is the system ID. Matching is forgiving about case and punctuation, so snes, SNES, and S.N.E.S resolve to the same system.
Custom names take priority over names.txt, Frontend's built-in regional names, and names reported by Core.
Regional system names
Frontend also includes built-in regional system names and logo variants. Open Settings > Language, then set Region to Automatic, Americas, Europe, or Japan.
Use custom system names when you want a specific name regardless of the regional setting.
MiSTer names.txt
On MiSTer, Settings > Language > MiSTer names.txt uses the system names from /media/fat/names.txt, the file MiSTer's own menu uses to rename cores. It's off by default. A line only renames the system whose ID matches its key, so SNES: renames SNES, while Gameboy: renames Game Boy and leaves Game Boy Color alone. Systems the file doesn't name keep their usual name, and Region still picks the logos.
Frontend reads the file at startup or when you turn the setting on, so restart Frontend after editing it.
System logo style
Frontend ships its built-in system logos in two styles. Settings > Appearance > System logos switches between Tinted, which follows the active color scheme, and Full color. Tinted is the default. This setting only affects the built-in logos, not your own system artwork.
Background
Settings > Appearance > Background puts an image behind every screen:
- Background image: pick an image file, or open a folder and choose Use this folder to show a random image from it each time the MiSTer starts. No background image, in the picker's Menu, removes it. Images follow the same size limits as custom artwork, in PNG, JPEG, WebP, or BMP.
- Game background: shows the selected game's screenshot, fan art, title screen, or box art behind game lists once you stop on a game. The game needs that image type imported.
- Blur, Dimming, and Card style appear once an image is set. Blur softens the image, Dimming darkens it, with Readable as the setting that keeps text legible, and Card style puts the lists on Glass or Solid panels.
The settings are stored in frontend.toml:
[settings]
background_image = "/media/fat/wallpapers" # a file or a folder
game_background = "screenshot" # off, screenshot, fanart, titleshot, or boxart
background_blur = 50 # 0 to 100
background_dim = 0 # -6 is no dimming, 0 is Readable, up to 3
background_list_style = "glass" # glass or solid
Top bar logo
Settings > Appearance > Top bar logo chooses what the top bar shows: Zaparoo, Custom image, or None. Custom image adds a Logo image row to pick the file, which follows the same limits as custom artwork. The screensaver's Bouncing style bounces your image. Choosing None switches it to bounce the clock instead.
Changing the logo needs a device linked to a Zaparoo Online account with App Pro or Warp. Without one, the rows show a Pro badge and explain how to get it. If the device is unlinked, or Online reports that the account doesn't have it, Frontend goes back to the Zaparoo logo. Being offline changes nothing.
Screensaver
Settings > Appearance > Screensaver sets when the screensaver starts and what it shows:
- Start after: how long without input before it starts, from 1 to 30 minutes, or Off. The default is 5 minutes.
- Style: Random, the default, plays a different style each time the screensaver starts. The others are Bouncing, Spinning logo, System logos, Cover wall, Recent games, Paddle clock, Starfield, Flyby, Polygons, Snakes, Life, and Maze.
- Bouncing, shown for Bouncing and Random: bounce the Logo, the Clock, or a Recent game's cover.
The styles use the Zaparoo logo, the built-in system logos, and your games' cover art. Cover wall needs at least 8 covers, and a bouncing Recent game needs a recently played game with a cover. Without them, the screensaver bounces the logo instead. Random skips those styles until you have the covers.
The settings are stored in frontend.toml:
[settings]
screensaver_timeout = "300" # seconds: 60, 120, 300, 600, 900, 1800, or "off"
screensaver_style = "random" # random, bouncing, spinning-logo, system-logos, cover-wall,
# recent-games, paddle-clock, starfield, flyby, polygons,
# snakes, life, or maze
screensaver_bouncing = "logo" # logo, clock, or recent-game
Configuration file
Frontend stores its settings in /media/fat/zaparoo/frontend.toml and edits that file in place, so comments you add by hand survive. The Hub layout is a list of [[hub.items]] entries, one per tile, with a type of category, action, system, folder, zapscript, search, collection (a deck), setting (a Settings page), or blank and an id, path, or script to match. Tiles can also take a name and an icon:
[[hub.items]]
type = "category"
id = "Arcade"
[[hub.items]]
type = "action"
id = "favorites"
[[hub.items]]
type = "zapscript"
script = "**launch.random:SNES"
name = "Random SNES"
A folder tile with live = true and no system lists a folder straight from the SD card, as Custom folder... does:
[[hub.items]]
type = "folder"
path = "/media/fat/_RA_Cores"
live = true
Arranging tiles from the Hub writes this for you. Leave the [hub] known list alone; Frontend uses it to remember tiles you removed.
Saved searches
A search tile opens the results of a search. Save to Hub on the results writes one for you:
[[hub.items]]
type = "search"
name = "SNES and Genesis RPGs"
query = "final"
systems = ["SNES", "Genesis"]
tags = ["genre:rpg", "year:1994"]
| Key | What it does |
|---|---|
query | Text to match in game names. Leave it out to list everything the other keys allow. |
systems | System IDs to search. Leave it out to search every system. |
tags | Tags a game must have, written as type:value. |
path | Limits the search to one folder, as Search here... does. It is a full path, so edit it if the games move to another drive. |
A tile needs at least one of these keys.