Appearance Icons and Themes
FolderView Plus combines per-folder styling, built-in and custom icons, named appearance profiles, managed imported themes, compatibility modes, shared runtime tokens, and optional custom CSS.
The folder editor can use:
- Built-in FolderView Plus SVG icons.
- The separately versioned third-party icon pack.
- Uploaded custom icons.
- A direct supported image URL or data-image value.
- The default/fallback icon.
Clicking an eligible Docker/VM member icon in the picker can reuse it as the folder icon. A missing selected icon falls back safely; run Diagnostics to repair stale custom-icon references.
Basic mode emphasizes search and common results. Advanced mode adds pack, tag, and state filters. Available tools include:
- Text search and category/tag filters.
- All, Favorites, Recent, Suggested, and Duplicates scopes.
- Sort choices.
- Pack pinning and hiding.
- Active-filter badges and reset.
Pinning/hiding changes the picker experience, not the installed icon-pack contents.
Screenshot placeholder — third-party icon picker
Capture Basic and Advanced states, Find, Pack, Filters, scope choices, active-filter badges, and one selected test icon. Exclude private filenames.
Uploaded icons live in /boot/config/plugins/folderview.plus/images/custom and are restored into the runtime path after reboot or upgrade. The manager provides storage statistics, quota status, search/sort, usage counts, select-for-use, rename, delete, and replacement.
| Limit | Value |
|---|---|
| Allowed extensions | PNG, JPG/JPEG, GIF, WebP, SVG, BMP, ICO, AVIF |
| Maximum file size | 4 MiB |
| Maximum files | 2,000 |
| Maximum total storage | 256 MiB |
| Optimized maximum dimension | 1,024 px where optimization applies |
| Upload rate | 24 uploads per minute |
Identical-file deduplication normally reuses the existing icon. Replacement can overwrite the same target name after confirmation. Rename changes the stored file name; review the usage list and change existing folder references first so they do not become missing references. An icon still referenced by folders cannot be deleted until those references are changed or repaired.
SVG uploads are parsed and restricted to an allowlisted SVG surface; unsafe external/script-like content is not accepted. Still use icons from sources you trust.
Screenshot placeholder — Custom Icon Manager
Capture quota statistics, a search result, usage count, and rename/delete controls using fictional icon names.
Custom-icon binaries are not included in an environment export. Copy the full persistent plugin directory before uninstall or flash-device replacement. See Backup, Recovery, and Migration.
| Mode | Use |
|---|---|
| Auto | Detect the host theme and resolve the normal shared tokens. |
| Host | Follow host-provided values closely. |
| Safe | Use a conservative palette when host variables are unreliable. |
| High contrast | Increase visual separation and readability. |
Compatibility mode controls how FolderView Plus integrates with the current host theme. It is separate from managed imported themes and appearance profiles.
Advanced -> Appearance supports named profiles. A profile contains four layers:
| Scope | Applies to |
|---|---|
| Global | Every FolderView Plus surface. |
| Docker | Docker page overrides layered over Global. |
| VM | VM page overrides layered over Global. |
| Dashboard | Dashboard overrides layered over Global. |
For a scoped page, global variables/CSS are applied first and the page-specific layer overrides or appends to them. The active profile is the only profile resolved at runtime.
You can create, activate, preview, save scoped layers, and delete profiles. Preview validates the selected profile and scope without persisting it; Save writes the normalized variables and custom CSS atomically. Keep an alternate known-good profile before a large redesign. The final remaining profile cannot be deleted.
The normalized profile store accepts up to 32 profiles. Profile identifiers and names are bounded, duplicate identifiers are removed during normalization, and one valid active profile is always selected.
Screenshot placeholder — appearance profile scopes
Capture the profile selector, Global/Docker/VM/Dashboard scopes, token controls, and preview using a test profile.
Theme Workspace can scan a supported public GitHub source, preview discovered theme files, import a selected theme, and manage installed themes. Imported themes remain inactive until explicitly activated.
Available lifecycle actions include:
- Activate, deactivate, and delete.
- Customize tokens/CSS.
- Check for source updates.
- Preview individual or bulk update plans.
- Update one theme or a selected group.
Review a source before importing. Do not paste credentials or private access tokens into a public support report. Theme sources and files are bounded, normalized, and scanned, but imported CSS still changes what the browser renders.
Advanced capacity limits are 24 managed themes, 16 files per theme, 256 KiB per theme file, and 64 KiB for a custom-CSS layer.
Screenshot placeholder — Theme Workspace
Capture managed themes, activation state, update status, tokens, and a preview using a public test theme. Do not include private repository URLs or credentials.
Shared --fvplus-* variables control core surfaces. Prefer profile token overrides and documented stable selectors over broad rules. Avoid unscoped selectors such as button, table, or img, which can break Unraid and other plugins.
Legacy custom override roots from folder.view generations remain supported. Stable-selector compatibility and deprecation policy are documented in the repository's Support Policy.
Legacy custom JavaScript may still load from supported override directories, but it can interfere with navigation, observers, dialogs, and actions. Disable it first when diagnosing repeated refresh, blank pages, clipped menus, or stale state.
- Preserve focus indicators and keyboard navigation.
- Do not encode status through color alone.
- Test light, dark, high-contrast, and reduced-motion modes.
- Test 100%, 125%, and 150% browser zoom.
- Test desktop and smartphone widths.
- Keep started, paused, stopped, warning, and critical text/background combinations readable.
- Switch Theme compatibility to Safe or High contrast.
- Activate a known-good appearance profile or deactivate the imported managed theme.
- Disable custom CSS/JavaScript.
- Hard-refresh with
Ctrl+F5. - Confirm Settings and runtime pages separately.
- Restore a prior environment snapshot if Theme Workspace data itself is damaged.
- Export sanitized diagnostics if the failure persists.
See also: Compatibility and Performance · Backup, Recovery, and Migration · Troubleshooting