| Switch Theme Injector | |
|---|---|
 | |
| General | |
| Author | exelix11 |
| Type | Theme Tools |
| Version | 4.7.1_2.7.1 |
| License | GPL-2.0 |
| Last Updated | 2022/10/14 |
| Links | |
| Download | |
| Website | |
| Source | |
| Support Author | |
The Switch theme injector project is split into three parts.
- Switch theme injector (Windows app) - An app to create and edit custom themes.
- NXThemes installer - An homebrew app that runs on the switch itself and can be used to install and manage themes.
- Switch theme injector online (also called WebInjector) - A port of the Windows injector as a web app, it lacks some features like custom applet icons and common.szs layouts support.
The main objective is to develop a complete toolset to create and install custom themes on the switch. As the console os doesn't implement custom themes natively most of this is done by patching system SZS files to get the desired aspect.
Unfortunately, SZS files from the switch os contain copyrighted data and can't be shared online that's why the nxtheme format has been developed, it contains only differential info and can be freely shared. Unless you're dealing with making your own patches and custom layouts you should only use nxtheme files.
Note: while custom themes don't seem to cause bans, when in CFW you should not be connected to the internet or at least you should be using a dns (even if you don't use themes).
Features
- An app to create and edit custom themes.
- An homebrew app that runs on the switch itself and can be used to install and manage themes.
- A port of the windows injector as a web app, it lacks some features like custom applet icons and common.szs layouts support.
- The main objective is to develop a complete toolset to create and install custom themes on the switch.
- To use custom themes you need an hacked switch that's at least on Firmware 5.0.
- Switch theme injector online.
User guide
Installing Themes
The most common scenario for installing themes is to use the theme installer homebrew. Here are the steps to follow:
- Create a folder called "themes" in the root of your SD card.
- Copy your themes in either nxtheme or szs format into this folder.
- Launch the theme installer and select your desired theme to install it.
- Reboot your console and your new theme should be applied.
Note that each file is a single home menu part (eg just the lockscreen or just the main menu), a full home menu theme is composed by multiple nxtheme files.
To remove a theme just select uninstall in the theme installer. You can just install a different theme to overwrite the currently installed one.
When a new firmware comes out before upgrading (or downgrading) remember to uninstall any theme you have installed to avoid compatibility issues, if you forget your console may not boot untill the theme is removed as explained next.
In case your console doesn't boot anymore due to a bad theme (mostly with szs themes) delete the \atmosphere\contents\01000000001000 folder from your sd (it's \<cfw name>\titles\01000000001000 for old atmosphere and other CFWs), now your console should be booting, launch the theme installer and select uninstall theme to finish the cleanup process.
Making themes
To make themes, you can use either the Theme injector application or the web version.
In the past, themes were distributed as szs files. However, this format is no longer supported because these szs files also contain copyrighted data. Instead, you should only use the nxtheme format.
Making an nxtheme
How to make a theme:
- Open the windows app.
- go to the "nxtheme builder" tab.
- Select the home menu part you want to theme.
- Click on "..." and open any 1280x720 JPG image (Note that the web version only supports JPG files).
- If you want, select a custom layout.
- Click on "Build nxtheme".
Note that if you'd like you can also make a theme with just a custom layout without any bg image, just select a layout without opening any image.
For making themes, you can only use JPG images or DXT1-encoded DDS images. For best quality, it’s better to manually encode the image to DDS so you can have a preview of how it will look like with the compression applied.
Linux support
The GUI only works on Windows. However, on Linux, you can use the CLI through mono. You will need the "mono-complete" package. Then, you should be able to launch the app by running "mono SwitchThemes.exe help".
Command line usage (CLI)
Building nxthemes:
SwitchThemes.exe buildNX home "<your image.png/jpg/dds>" "<json layout file, optional>" "name=<theme name>" "author=<author name>" "out=<OutputPath>.nxtheme"
This will build a theme for the home menu, instead of home you can use: lock for lockscreen, apps for the all apps screen, set for the settings applet, user for the user page applet and news for the news applet. Only the image and out file args are needed.
Other options specific to the theme target such as applet icons are availbale as well, run SwitchThemes.exe help for more info.
Remote install:
Launch the theme installer and select remote install, then run the following command:
SwitchThemes.exe install 192.168.X.Y “<nxtheme/szs file>”
Where 192.168.X.Y is your console IP address.
Custom layouts
Custom layouts are JSON files that allow you to change the appearance of the home menu by moving the UI components. To create a custom layout, you will need the original home menu szs files found in /themes/systemData on your SD card (if you ever used the theme installer) and a tool capable of editing them like the Switch Layout Editor.
You can find more information about layouts and the supported properties here.
For layout editing, read the Layout editor wiki to get started. Parts of the main home menu layout are documented in this repo wiki.
FAQ
Q. Can a custom theme brick my switch?
No, custom themes are applied through layered fs, so no change is made to your NAND.
Q. The theme installer crashes on launch or just fails to install themes.
There are two main causes: the archive bit is set for the themes folder and the SD card is corrupted. The former happens mainly if you use a Mac but really depends on how you create the themes folder. The latter is often caused by exFAT on your SD card. Try to delete the themes folder and launch the installer, and it will create it again. Now just copy the themes, and it should work.
If it still doesn't work, it could be corruption. In this case, the best option is to backup the SD contents and format it to FAT32. If you have games installed, don't worry as the Switch OS automatically splits them into <4GB parts so they work on every SD.
Q. I installed a theme and now my switch crashes on boot or I had a custom theme, then I updated my console and now it crashes on boot.
Delete the /titles/0100000000001000 and/or /titles/0100000000000811 folders from the CFW folder on your SD card.
At this point, your console will boot up normally. To clean up any leftovers, launch the theme installer and select “uninstall theme”.
Q. Why are nxtheme files better than SZS?
They're legal. This means they can be freely shared, and they are firmware-independent so they can be installed on any firmware.
It is also a more flexible format that can be extended in the future to support more features such as theme packs.
Q. Why only 720p images? I want to use a 1080p or 4K one!
Two reasons: first, the internal resolution of the home menu is 720p no matter if docked or not. This means your image will automatically be scaled down to 720p.
Second, the home menu memory is very limited. A bigger image is more likely to crash on boot and would allow for less customization.
Q. The news applet crashes.
If you're experiencing crashes with the news applet on your Nintendo Switch, it may be due to using an outdated bflyt patch.
Check out the spoiler at the beginning of the thread for more information and use this tool to fix your themes.
Q. Are themes compatible with older firmware versions before 5.1.0?
While this tool should work for older firmwares, we haven't tested it. If you'd like to try, you'll need to use a common.szs from the firmware version you want to modify and follow the guide provided.
If your theme works, please let us know! Note that if you encounter any issues with older firmwares, we may not be able to provide assistance.
Update: Version 4.0.1 has been tested and works, but there may be some issues as reported by hax4dayz.
Q. Can the Switch theme injector app run on Linux?
Yes and no. The UI won't work, but you can still create themes using the command line interface (more information available on GitHub). Additionally, you'll need to provide images in DDS file format as the included converter requires DirectX, which is only available on Windows.
If you want to stay up-to-date on any future updates or learn more about this project, be sure to join the Discord server and follow the thread for notifications.
Screenshots
Media
Custom Themes Nintendo Switch TUTORIAL (Manito)
Compatibility
To use custom themes you need an hacked switch that's at least on Firmware 5.0.
Changelog
Version 4.7.1 & NXThemesInstaller 2.7.1
- Support for 17.0
- Expose patch templates functionality in the PC theme injector, allows for patching custom szs files
- Minor changes in bflan serialization, mostly for the layout editor
Version 4.7 & NXThemesInstaller 2.7
- Support for firmware 14.0 and 14.1 #113.
- The reboot button now uses spsm instead of bpc, this means the console will shut down properly #111.
- Auto update for home menu patches, whenever a new firmware drops if it just needs a new IPS patch it will be downloaded automatically from github as soon as it's available.
- This means there won't be firmware specific releases anymore unless something major breaks.
- If you don't want to connect your console to the internet you can download the new patches manually from github, there is a guide in the readme.
- If you want to get notifications for new updates as soon as they're available click watch on the theme-patches repo.