Ultrahand Overlay 2.5.3

List of Changes

1. Proper return context has been established for open commands in packages.
   • Clicking back from an overlay opened via open command now takes you to exactly where you left off in the package.
   • With this change, overlays can now be crafted to be proper extensions / plugins for packages themselves to leverage.
2. Add field=value JSON array lookup (by @Niklas080208 in #326).
   • In place of indexes for arrays in JSON data entries, users can now specify a matching field = value contained in the corresponding array instead.
3. Improved touch handling (from latest libultrahand).
4. Various code and library optimizations.
   • Over 160 KB smaller than v2.5.2 (now the smallest version since v1.1.6).
5. libnx and other development libraries have been updated.
   • Now using libnx 4.12.0-1.
6. Now bundled with nx-ovlloader v2.0.3.
   • Important: nx-ovlloader v2.0.3 is vastly fine from testing and reports from a wide variety of users, but one is reporting an issue that will take more time to investigate properly. For the time being, we will be sticking with nx-ovlloader v2.0.2. - 07/18/2026 2:54 AM PST
7. Various bug fixes and corrections.

Full Changelog: d706cd8...v2.5.3

Ultrahand Overlay 2.5.2

List of Changes

1. New ;text_color= and ;footer_color= command headers for command list items.
   • ;text_color=<HEX> and ;footer_color=<HEX> (rgb888, e.g. #RRGGBB or RRGGBB) set a custom title/value color for that specific item.
   • Applies to standard list items, toggles, and dropdown-selection items; takes priority over theme defaults but never overrides transient run-state colors (spinner/checkmark/crossmark/in-progress).
2. New ;bg_color= and ;border= table command headers.
   • ;bg_color=<HEX> sets a custom table background color. Only the RGB channels are used (alpha is still read from the theme).
   • ;border=true/;border=false toggles the table's border on or off independent of Dynamic Tables.
3. New matching_hex_val_custom <FILE_PATH> <ASCII_PATTERN> <OFFSET> <HEX_VALUE> conditional command (and inverse !matching_hex_val_custom).
   • Resolves <OFFSET> relative to the file offset of <ASCII_PATTERN> (e.g. "CUST"), using the same magic-scan + offset cache that hex-by-custom-offset writes use.
   • Usable standalone or with ;visibility_condition=/;toggle_state_condition=, same as the other matching_* checks.
4. New In-Package Titles toggle in Widget Settings (in_package_titles, on by default).
   • Separate from the existing Package Titles toggle. When off, every in-package (sub-menu) title is forced to the theme's default package title color, overriding any color a package requested via its own header (e.g. ;color=).
5. Input handling changes to prevent accidental hides while a command is running.
   • X now hides the overlay while a command is running (moved off B), so reflexively pressing B to "go back" no longer hides the overlay mid-command.
   • B is swallowed during a running command instead of hiding or popping the menu.
   • D-pad and A now visibly bounce the highlighted item while a command is running, instead of incorrectly triggering a click animation.
6. Settings menu navigation bug fixes.
7. Fixed overlay/package list titles and versions not switching to the theme's Selection Text/Value color when highlighted.
   • These now use the new base-color path internally, so highlighting behaves correctly again while still supporting the new ;text_color=/;footer_color= per-item overrides.
8. Slight changes to the default theme colors and settings.
   • Dynamic Logo now defaults to off instead of on.
   • Side-note: For color changes to be applied, users must re-apply their default theme, or install Ultrahand fresh.
9. Refreshed default theme colors (click, dynamic logo, main logo, and table background), and added a new bundled classic.ini theme.
   • classic.ini preserves the exact pre-2.5.2 default color palette for anyone who prefers the previous look.
10. Improved download reliability for usage with a wider range of url domains.
11. Foreground related bug fixes in libultrahand.
12. Fixed a mismatched declared size on the default key-combos array.

Full Changelog: v2.5.1...v2.5.2

Quick Update

• Foreground request related bug fixes. - 07/10/2026 02:54 AM PST
• Slight tweaks to default theme. - 07/10/2026 4:20 AM PST
• New table wrapping mode auto + bug fixes for notification translations / alignments. - 07/10/2026 7:35 AM PST
  • auto utilizes character wrapping for Asian languages and word wrapping for non-Asian languages.
• New Ultrahand config.ini key swipe_offset (integer value; optional) for calibrating the swipe to open behavior's X-start. - 07/10/2026 7:35 AM PST
• Hard line break fix for table wrapText (proper handling of newlines). - 07/10/2026 08:04 AM PST
• Add translation handling in CategoryHeader constructors. -07/10/2026 8:33 AM PST
• Translations now apply to sections on divider split strings, new {ovl_language} placeholder for overlay language, bug fix for hard line break changes. - 07/10/2026 10:01 AM PST
  • {ovl_language} returns values like en, es, etc based upon the selected language in the Ultrahand settings menu.

Full Changelog: v2.5.2...d706cd8

Ultrahand Overlay 2.5.1

Stability Update

List of Changes

• Ultrahand package bug fix for placeholder resolution within sourced commands.
  • This bug appears to have been introduced in v2.4.5.
• No changes to libultrahand v2.5.0.

Full Changelog: v2.5.0...v2.5.1

Ultrahand Overlay 2.5.0

List of Changes

1. New Switch 2 Style toggle in Theme Settings (Misc), on by default.
   • When enabled, selected list items, the cursor, trackbar handles are replaced with a more rounded, slightly wider cursor utilizing the new color-wheel effect.
   • Toggles render as a sliding Switch-style pill switch instead of a plain ON/OFF glyph.
   • Single-choice selection lists draw a circular radio mark in the value slot instead of a checkmark.
   • Turning the toggle off preserves the classic Switch 1 look from before v2.5.0.
   • Side-note: requires libultrahand v2.5.0 or greater; compiled overlays built against older libultrahand versions are unaffected.
2. Radio-style selection lists.
   • Themes, Wallpapers, Sounds, Language, Launch Combos, Priority, and package ;mode=option dropdown menus now use the new circular radio mark in place of a checkmark when Switch 2 Style is on.
3. New theme INI color keys added.
   • Cursor
     • s2_highlight_color_1: first fixed accent in the default rotating highlight wheel (cursor/selection border).
     • s2_highlight_color_2: second fixed accent in the default rotating highlight wheel.
     • s2_highlight_color_3: bright hero color in the default wheel.
     • s2_highlight_color_3_deep: deep/shadow variant of s2_highlight_color_3.
     • s2_highlight_color_4: second bright hero color in the default wheel.
     • s2_highlight_color_4_deep: deep/shadow variant of s2_highlight_color_4.
     • s2_alt_highlight_color_1: first fixed accent in the alternate wheel (shown while locked or mid-click).
     • s2_alt_highlight_color_2: second fixed accent in the alternate wheel.
     • s2_alt_highlight_color_3: bright hero color in the alternate wheel.
     • s2_alt_highlight_color_3_deep: deep/shadow variant of s2_alt_highlight_color_3.
     • s2_alt_highlight_color_4: second bright hero color in the alternate wheel.
     • s2_alt_highlight_color_4_deep: deep/shadow variant of s2_alt_highlight_color_4.
   • Table Border
     • s2_table_border_color_1: first fixed accent in the rotating table-border wheel.
     • s2_table_border_color_2: second fixed accent in the rotating table-border wheel.
     • s2_table_border_color_3: bright hero color in the table-border wheel.
     • s2_table_border_color_3_deep: deep/shadow variant of s2_table_border_color_3.
     • s2_table_border_color_4: second bright hero color in the table-border wheel.
     • s2_table_border_color_4_deep: deep/shadow variant of s2_table_border_color_4.
     • table_border_color: base color of the new table border, used when Dynamic Tables is off.
   • Widget Border
     • s2_widget_border_color_1: first fixed accent in the rotating widget-border wheel.
     • s2_widget_border_color_2: second fixed accent in the rotating widget-border wheel.
     • s2_widget_border_color_3: bright hero color in the widget-border wheel.
     • s2_widget_border_color_3_deep: deep/shadow variant of s2_widget_border_color_3.
     • s2_widget_border_color_4: second bright hero color in the widget-border wheel.
     • s2_widget_border_color_4_deep: deep/shadow variant of s2_widget_border_color_4.
   • Switch 2 UI Elements
     • s2_radio_ring_color: outer ring of an unselected radio mark.
     • s2_radio_selected_color: fill color once a radio choice is confirmed.
     • s2_radio_inprogress_color: fill color while a radio choice is mid-selection.
     • s2_radio_inner_color: small inner dot drawn inside a filled radio mark.
     • s2_toggle_on_color: toggle track color when the toggle is on.
     • s2_toggle_off_color: toggle track color when the toggle is off.
     • s2_toggle_circle_color: color of the toggle's sliding knob.
   • Preliminary updates for the bundled ultra.ini and ultra-blue.ini themes.
   • Side-note: custom themes that don't define these keys fall back to libultrahand's built-in defaults.
4. Widget Settings tweaks.
   • Dynamic Colors has been renamed to Dynamic Temps.
   • New Dynamic Border toggle (animates the widget's border color according to the theme colors).
5. Theme Settings: new Dynamic Tables toggle (default on).
   • Drives the new border effect drawn around package table sections; independent of the Switch 2 Style toggle.
   • When off, tables resort back to the table_border_color theme ini preset.
6. Bug fix for nested placeholders.
   • Placeholder resolution is now depth-aware.
   • A placeholder whose inner content hasn't resolved yet is now left intact for a later pass instead of producing a premature null.
7. Settings menu navigation bug fix.
   • Added a recovery guard that re-derives the settings menu/sub-menu state if both navigation flags are unexpectedly cleared (e.g. after a rapid back-press chain or an interrupted hide/show transition), preventing the menu from getting stuck.
   • Fixed a stale sub-menu flag for combo-mode entries that could cause a double-pop on the next B press.
8. Various alignment corrections.

Full Changelog: 9b965b1...v2.5.0

Ultrahand Overlay 2.4.5

List of Changes

1. New conditional {if_...} placeholder method.
   • null
     • {if_null(<VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])} returns TRUE_FALLBACK when VALUE resolved to null (the literal returned by an unresolved/missing placeholder).
   • !null
     • {if_!null(<VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])} is the inverse.
   • ==, !=
     • {if_==(<VALUE>,<COMPARE_VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])} and {if_!=(...)} do exact string equality.
   • >, <, >=, <=
     • {if_>(<VALUE>,<COMPARE_VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])}, {if_<(...)}, {if_>=(...)}, and {if_<=(...)} compare numerically when both values are numbers (compared as floats), and fall back to a plain lexicographic (case-sensitive) comparison otherwise.
   • version_>, version_<, version_>=, version_<=
     • {if_version_>(<VALUE>,<COMPARE_VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])}, {if_version_<(...)}, {if_version_>=(...)}, and {if_version_<=(...)} do version-aware comparison.
     • Numeric segments compare as integers (1.10.0 > 1.9.0).
     • - suffix is treated as a pre-release and sorts lower (2.0.1-rc < 2.0.1).
     • + suffix is treated as build metadata and sorts higher (2.0.1+r23 > 2.0.1).
   • The FALSE_FALLBACK is optional in every form. When omitted, the false branch returns VALUE unchanged.
2. New {crc32(<FILE_PATH>)} placeholder method.
   • Returns the CRC32 of a file as 8 uppercase hex characters, or null if the file can't be read.
   • Useful with the {if_...} and matching_* checks for verifying file contents.
3. All placeholders can now be composed to define any source declaration.
   • All placeholder variable declarations are fully resolved in order before being used.
   • All placeholder commands (excluding _source) can be nested and chained to build the final _source declaration.
     • Side-note: No commands are executed at this stage; only placeholder expressions are evaluated.
   • Non-source variable placeholders can now be redefined mid-section in sourced commands.
4. New standalone conditional commands for use in packages.
   • path_exists <PATH>
   • ipc_exists <SERVICE_NAME>
   • module_exists <TID> (true when the module's content folder exists, running or not)
   • module_is_active <TID> (true only when the module is currently running)
   • matching_txt_line <FILE_PATH> <TEXT_LINE>
   • matching_hex_val <FILE_PATH> <OFFSET> <HEX_VALUE>
   • matching_ini_val <FILE_PATH> <SECTION> <KEY> <VALUE>
   • Each runs as its own command and resolves to success or failure, so it can be used mid-script to force a command failure or success (handy with try: logic).
   • Prefix any of them with ! to invert the result (!path_exists, !module_exists, etc.).
5. New ;visibility_condition= option directive for usage with all command objects.
   • ;visibility_condition=<MODE> <ARGS> draws a menu item or section only when the condition is satisfied; otherwise the item is skipped at render time.
   • Accepts any of the conditional modes above (path_exists, ipc_exists, module_exists, module_is_active, matching_txt_line, matching_hex_val, matching_ini_val) with ! negation, and resolves placeholders inside the condition.
   • An empty condition (as well as a successful condition) shows the item; an unknown mode, missing argument (or false condition) hides it.
   • Revised integration from PR #309.
6. New ;toggle_state_condition= option directive.
   • Sets a toggle's initial ON/OFF state from a live condition instead of an on/off path check. Uses the same conditional modes as ;visibility_condition=. A satisfied condition starts the toggle ON.
   • Revised integration from PR #309.
7. New ;hold=true directive for hold-to-activate items.
   • Add ;hold=true to a command list item or a toggle to require the user to hold the action before it fires.
   • While held, the item shows the in-progress symbol; execution is deferred until the hold completes, and the action can be cancelled by releasing early.
   • The hold length is set globally by the new Hold Duration trackbar (see below).
   • The built-in default Reboot/Shutdown package now ships its Shutdown entry with ;hold=true.
8. New module command for starting and stopping sysmodules.
   • module start <TID> launches a sysmodule by program ID.
   • module stop <TID> stops a sysmodule, graceful-first with a force-kill fallback for dynamic modules.
   • Reads the module's toolbox.json for its shutdown contract; static modules with no graceful contract are refused rather than risking an unsafe kill.
   • <TID> accepts a bare 16-hex-character folder name or a 0x-prefixed program ID.
9. New ipc-exec <SERVICE_NAME> <ENUM_CMD> command.
   • Sends a void to void IPC command to a service; success means the dispatch was accepted.
10. New ntp-sync <NTP_URL> command.
    • On-demand clock sync to the NTP host you specify.
    • Checks for internet access internally before attempting the sync.
11. New refresh-return command for sourced commands (dropdown menus).
    • When returning from a sourced selection, refresh-return redraws the entire prior menu and lands the cursor back on the item you came from, instead of a plain back.
    • Calling is optional. Without is faster, so only use refresh-return when the prior menu needs to be rebuilt to reflect changes (e.g. values that conditions key off of).
12. New refresh combos command argument.
    • refresh combos reloads the launch key combos live, so changes take effect without restarting the overlay. This joins the existing refresh theme, refresh package, and refresh wallpaper arguments.
13. New Input Settings section added to Misc.
    • Houses Launch Combos, Swipe to Open, Haptic Feedback, and the two new input options below.
    • New Stick Navigation toggle. When on, the analog stick navigates menus alongside the D-pad; when off, only the D-pad navigates. Applies to all libultrahand v2.4.5+ overlays.
    • New Hold Duration track-bar. Sets the global command hold-A length for all hold-to-activate actions, from 0.5s to 5.0s (default 3.0s).
14. Settings menu reorganized and renamed.
    • Page Recall and Launch Recall toggles have been removed. These behaviors are now always on.
    • The old Features header is now Feature Settings.
    • Auto NTP Sync is renamed NTP Sync Downloads.
15. The handheld / docked ;state= directive renamed to ;device_state=.
    • IMPORTANT: Packages that used ;state= must update to ;device_state=.
16. ini_file_source now supports wildcard paths.
    • A wildcard ini_file_source path enumerates every matching .ini and merges their section names (empty names skipped, duplicates removed, first occurrence wins).
    • Multiple ini_file_source lines now accumulate sections together rather than each one replacing the last.
    • Revised integration from PR #312.
17. The default root package now includes an INI Entry for /bootloader/ini/*.ini entries in Reboot To.
    • Side-note: Users may want to delete /switch/.packages/package.ini to have this command updated.
    • Revised integration from PR #312.
18. mirror- is now accepted as an alias for mirror_ (mirror-copy, mirror-cp).
    • Side-note: This follows the loose convention where - are used with action commands (set-ini-val, sync-ntp, etc) and _ are used to for check commands that simply resolve to success or failure (path_exists, matching_ini_val, etc).
19. The overlay version placeholder {ovl_version(<OVL_PATH>)} now works with relative path resolution (i.e. ./ and ./../).
20. Cleaner dock power-down protocol on reboot and shutdown commands.
    • A USB-PD teardown is now staged before any shutdown so the console signals the dock to cut its 5V rail before the PMIC powers off.
    • Bug fix from Issue #313.
21. New Overlay does not exist! notification for attempting to launch an overlay file that does not exist.
    • Launching a mode whose overlay file is missing now reports the missing overlay directly instead of misreporting it as AMS-incompatible.

New Contributors

• @Niklas080208 made their first contribution in #312
• @rashevskyv made their first contribution in #309

Full Changelog: v2.4.4...v2.4.5

Quick Update

• ;device_state= processing bug fix. - 06/11/2026 8:00 AM PST
• Variable placeholder definition / redefinition and resolutions bug fix. - 06/11/2026 8:00 AM PST

Full Changelog: v2.4.5...9b965b1

Ultrahand Overlay 2.4.4

Stability Update

List of Changes

• Quick bug fix for the exit package command.
  • In the prior version triggering exit package was preventing the package header from being properly cached for forwarder packages until Ultrahand exits.
    • This broke things like package versions, titles, and info sections in package forwarders from being properly cached after triggering (now resolved).
• Side-note: Compiled with libultrahand v2.4.3 (v2.4.4 will be skipped on this release; no changes).

Full Changelog: v2.4.3...v2.4.4

Ultrahand Overlay 2.4.3

List of Changes

• Sleep halting of the background event poller in libultrahand (to prevent all polling activity during shallow sleep).
  • This makes the CPU load contribution from the overlay 0% during shallow sleep.

Full Changelog: v2.4.2...v2.4.3

Ultrahand Overlay 2.4.2

List of Changes

1. New package command option header ;ram_size_gb= for conditionally drawing commands based on detected system RAM.
   • ;ram_size_gb=4 will only apply on 4GB systems, ;ram_size_gb=8 on 8GB systems.
   • RAM size is detected at fuse data write time and cached.
     • Older fuse files without this key are updated automatically on next startup.
2. New package placeholders: {ram_size_gb}, {hekate_version}, {ovlloader_version}, {ultrahand_version}, and {ovl_version(<PATH_TO_OVL>)}.
   • {ram_size_gb}: returns 4 or 8 based on detected system RAM (read from fuse data).
   • {hekate_version}: reads from sdmc:/bootloader/update.bin and is cached at startup.
   • {ovlloader_version}: reads from the running loader info and is cached at startup.
   • {ultrahand_version}: returns the currently running Ultrahand version.
   • {ovl_version(<PATH_TO_OVL>)}: dynamically reads the version of any overlay by path.
3. Expanded exit command with new destination arguments.
   • exit package instantly returns to the packages menu from anywhere in the package nav stack (including nested menus and script overlays) with the cursor positioned on the originating package.
   • exit overlays and exit packages have been renamed to exit to_overlays and exit to_packages.
   • exit ovlloader triggers a complete exit of nx-ovlloader.
4. Expanded reboot command reboot ovlloader command using the same reload flag mechanism as exit ovlloader.
   • Triggers an nx-ovlloader reload on demand without requiring a heap size change.
5. nx-ovlloader version is now compared before and after a Software Update.
   • If a version change is detected, Ultrahand automatically triggers a reload so the new loader takes effect immediately without a manual reboot.
6. New force_failure command.
   • Explicitly marks command execution as failed (useful for try: logic in packages).
7. Scope fix for exec commands.
   • executeIniCommands now correctly derives the package path from the ini file's actual location rather than always defaulting to the calling package's path.
8. Bug fix for ;mode=option drop-down losing the option symbol on back when no value has been set.
   • Footer now correctly restores to OPTION_SYMBOL as the default rather than an empty/null string.
9. Name split footer normalization fix for option-mode checkmark matching.
   • Footers written by boot_package (e.g. "0 - (default)") now correctly restored in SelectionOverlay after subsequent value changes.
10. Table fixes / improvements.
    • Lines beginning with ; are now skipped (comment-out support for table rows).
    • Rows where a placeholder resolves to "" now correctly shift columns instead of rendering a blank first column (bug fix).
    • The section and info columns now wrap independently to their own available widths, with rows aligned pairwise so multi-line entries in either column don't go out of sync.
    • Creator field text wrapping mode corrected from "none" to word wrapping.
11. Bug fix for PROTECTED_FILES (atmosphere/package3, atmosphere/stratosphere.romfs) not being correctly staged to .ultra during copy, move, and unzip operations.
    • These changes fix updating AMS from Ultrahand via reboot payload in more test cases.
12. IDDQ fuse calibration values now correctly scaled on write (cpu_iddq x4, soc_iddq x4, gpu_iddq x5) to match hekate.
13. Scroll bar object rendering corrections in libultrahand.
14. atmosphere.rgba wallpaper is now bundled in sdout.zip.
15. New master volume IPS patch included (d1e98d469...ips) for latest HOS support.
16. Now packaged with nx-ovlloader v2.0.2.

Full Changelog: 59b531c...v2.4.2

Ultrahand Overlay 2.4.1

List of Changes

1. Widget now has an optional border (on by default).
   • New theme color widget_border_color.
   • New toggle for Border in Settings > Widget.
   • Themes ultra.ini and ultra_blue.ini have been updated.
2. Improved audio event handling (for simultaneous sound effect playbacks) in libultrahand.
3. Improved combo input isolation and button event handling.
4. Home event system tick flag storing in libultrahand (for devs only).
5. Slight alignment corrections.

Full Changelog: v2.4.0...v2.4.1

Quick Update

• Slight widget alignment correction for the 100% battery case. - 04/20/2026 5:02 AM PST
• hide_widget_border variable loading bug fix in libultrahand. -04/20/2026 7:45 AM PST

Full Changelog: v2.4.1...59b531c

Ultrahand Overlay 2.4.0

List of Changes

1. Across the board performance optimizations to rendering methods in libultrahand.
   • Significantly improved wallpaper rendering performance (60FPS on 612 MHz cpu under-clock).
2. Across the board optimizations to all libultra functions in libultrahand.
   • Now compiling back to pre-Ultrahand Overlay v1.1.7 sizes. 😎
3. Overlay memory mode features have been expanded.
   • 6MB overlay heap now supports wallpapers and higher buffer sizes (faster copy, downloads, unzip, etc).
   • 4MB overlay heap now supports sound effects and slightly higher buffer sizes.
4. Improved table drawing (significantly better performance + various bug fixes).
5. Download commands now perform a NTP sync to pool.ntp.org one time after initial startup when called.
   • This feature will auto-fix issues with SSL handshakes breaking due to time de-synchronization.
   • New Auto NTP Sync toggle in the Settings > Miscellaneous menu for disabling this feature.
6. New Page Recall and Launch Recall toggles in Settings > Miscellaneous.
   • Page Recall preserves memory of what item you were on on page left / right for proper recall back to that item (on by default).
   • Launch Recall takes you back to the exact overlay / package you used a launch combo to enter on the main menu when you click such combo again (on by default).
     • When turned off, combo returns simply return to Ultrahand cold (like before).
     • Side-note: This function only works with overlays compiled with >=libultrahand v2.4.0.
7. Max overlay / package sort priority has been increased from 20 to 25.
8. Critical bug fixes for page swapping / swapTo in libultrahand.
   • There was an issue where rapid tapping of page left / right could trigger a broken GUI pointer (crash).
     • This issue is now resolved.
9. Improvements to feedback (sound + haptics).
   • Both sound and haptics now use their own threads for improved reliability with event synchronization for improved performance.
10. Numerous additional tweaks and unmentioned bug fixes.

Full Changelog: 7df15c9...v2.4.0