Onion OS themes are the reason no two OnionOS handhelds look alike. They are also one of the easiest things to get wrong, because "theme", "icon pack" and "box art" are three different systems that people routinely mix up. This covers the first two. For an introduction to the firmware itself, see the OnionOS guide.
What a theme actually changes
An OnionOS theme is a package that replaces the visual layer across the whole system — not just the main menu. Applying one changes:
- the background image
- the entry categories and how they are drawn
- console and system icons
- fonts
- background music
Because themes apply globally to every Onion app, a well-made one makes the device feel like a coherent product rather than a launcher with a wallpaper. A badly-made one makes half your menus unreadable, which is why it is worth sticking to the maintained repository rather than random forum downloads.
What a theme is not
It is not box art. Themes style the interface; box art is the per-game imagery that shows up next to your ROMs. They are separate systems with separate setup, and installing a theme will not populate artwork for your games. That is covered in how to add box art in OnionOS or GarlicOS.
It is not an icon pack, quite. Some themes bundle icon packs; standalone icon packs also exist and can be applied on top of a theme. Standalone icon packs need Onion v4.1 or newer, while themes themselves work from v3.9 up.
How to install an OnionOS theme
The process is deliberately simple:
- Download the theme you want from the community repository.
- Copy the file into the
Themesfolder on your SD card. - On the device, open the Themes app and select it.
You do not need to unzip anything — the Themes app unpacks a zipped theme when you apply it, which keeps the card tidier and the transfer faster. There is no reboot required; the change applies immediately, and switching back is just selecting the previous theme.
If a theme does not appear in the app, it is nearly always because it landed one folder too deep. Themes belong directly inside Themes, not inside a subfolder within it.
Where to get themes
The OnionUI Themes repository is the canonical source and it is genuinely large: roughly 186 original community themes, 15 remixed variants, 59 themes bundled with icon packs, and 9 standalone icon packs. Everything there is made for Onion specifically, which is the important part — themes built for other firmware will not work.
Because it is a community repository, quality varies. Preview images are your friend, and the on-device Themes app lets you preview before committing.
Themes worth trying first
A few that show what the system can do:
System 9 — a clean, structured take that leans into legibility. If you are coming from stock and want something that feels like a designed OS rather than a mod, start here.
NanoSwitch Modern Dark — minimalist and dark, which suits the Mini Plus screen well in low light. Good example of a theme that stays readable at small sizes.
cherry os — minimalist with a bundled icon pack, and one of the better-looking soft-palette themes if you find dark themes drab.
RupeeCore — ships as a three-pack with custom background music and its own icon pack. A good demonstration of how much a theme can change the character of the device, music included.
Counter Strike 1.6 — proof that the repository is not all tasteful minimalism. Game-inspired themes are a whole category, and half the fun of the theme system is that they exist.
Making your own
Themes are folders of images and configuration, not compiled packages, so editing one is genuinely approachable: copy an existing theme, swap the background, adjust the icons, and reapply. Starting from a theme close to what you want beats starting from scratch, and it teaches you the folder structure in about ten minutes.
Two practical notes. Keep image dimensions matching the theme you copied, or elements will stretch. And test on-device rather than judging from your monitor — a background that looks subtle at desktop size can be muddy on a 2.8-inch screen.
Troubleshooting
The theme is installed but nothing changed. Make sure you applied it in the Themes app; copying the file to the card only makes it available.
Text is unreadable over the background. A mismatch between the theme's font colour and its background. Either pick a different theme or swap the background image for something with less contrast noise.
Icons are missing after applying an icon pack. Standalone icon packs need Onion v4.1 or newer. Check your version before assuming the pack is broken.
Everything looks right but the music is wrong. Background music comes from the theme. If you want silence, that setting lives in the Onion settings rather than in the theme itself.
