Expand description
§native-theme
Cross-platform native theme detection and loading for Rust GUI applications.
Any Rust GUI app can look native on any platform by loading a single theme file or reading live OS settings, without coupling to any specific toolkit.
A Theme is sparse and TOML-shaped: every field is an Option, and it
holds a light and a dark variant. Resolving one variant fills every field
the model requires and checks its ranges, giving a ResolvedTheme that
UI code reads without unwrapping. Most applications use a toolkit
connector, which does this and converts the result:
native-theme-iced, native-theme-gpui or native-theme-egui.
§Quick start
Read the OS theme and pick its active variant (the OS readers need the
native feature, or kde, portal, macos, windows):
use native_theme::SystemTheme;
let sys = SystemTheme::from_system()?;
let active = sys.pick(sys.mode); // &ResolvedTheme
let _accent = active.defaults.accent_color;Load a bundled preset and resolve one mode (no features needed):
use native_theme::{ColorMode, Theme};
let resolved = Theme::preset("nord")?.resolve(ColorMode::Dark)?;
assert_eq!(resolved.mode, ColorMode::Dark);
let _background = resolved.variant.defaults.background_color;Apply an overlay to the OS theme; the overlay states only what it changes:
use native_theme::{SystemTheme, Theme};
let sys = SystemTheme::from_system()?;
let overlay = Theme::from_toml(r##"
[light.defaults]
accent_color = "#ff6600"
[dark.defaults]
accent_color = "#ff6600"
"##)?;
let customised = sys.with_overlay(&overlay)?;Hand the result to a connector: native-theme-iced, native-theme-gpui
and native-theme-egui each have from_system and from_preset, which do
the steps above, and to_theme, which converts a ResolvedTheme you
resolved yourself into the toolkit’s theme.
Watch for OS theme changes (the watch feature). The callback runs on a
background thread and carries no theme: clear the detection caches, which
hold the dark mode, reduced motion, accessibility preferences, icon theme
and, on Linux, desktop detected before (the OS read takes its icon theme
and desktop from them), and read the OS theme again. Keep the subscription
alive; dropping it stops watching:
let _subscription = native_theme::watch::on_theme_change(|_event| {
// Tell the UI thread to call `detect::invalidate_caches()`, then
// `SystemTheme::from_system()` again.
})?;§Presets
17 presets are bundled, each a TOML file with a light and a dark variant,
loaded by key with Theme::preset and listed by
Theme::list_presets (or Theme::list_presets_for_platform, the ones
offered on the running platform):
- Platform:
kde-breeze,adwaita,windows-11,macos-monterey(macOS 12 Monterey to 15 Sequoia),macos-tahoe(macOS 26 Tahoe),material-3andios-13(the flat look of iOS 13 to 18). - Community:
catppuccin-latte,catppuccin-frappe,catppuccin-macchiato,catppuccin-mocha,nord,dracula,gruvbox,solarized,tokyo-nightandone-dark.
material-3 and ios-13 have no OS reader; an application chooses them
as a look. ios-13’s SF Symbols icons load only on macOS (with
system-icons); elsewhere its icons are None, never another set’s.
§Platform readers
SystemTheme::from_system reads the OS theme with the running
platform’s reader and merges what it reads over that platform’s preset; a
field the reader does not supply keeps the preset’s value. Both variants
are resolved, so SystemTheme::pick serves either mode.
| Platform | Feature | Reads | Preset |
|---|---|---|---|
| KDE Plasma | kde | kdeglobals; with portal, the portal’s accent colour | kde-breeze |
| GNOME, Budgie | portal | the XDG Desktop Portal settings and gsettings | adwaita |
| macOS 11 and later | macos | NSColor under both appearances, NSFont, the scroller style and the accessibility options | macos-monterey before 26 (it covers 12 to 15), macos-tahoe from 26 |
| Windows | windows | UISettings, the system metrics and fonts | windows-11 |
The KDE, GNOME and Windows readers read the active variant only, and the
other variant is the preset’s; the macOS reader reads both. On another
Linux desktop, or without the desktop’s reader feature, from_system
returns the desktop’s preset (kde-breeze on KDE, adwaita elsewhere)
with no live reading, in the mode detect::detect_is_dark reads. On macOS and Windows without the reader feature it returns
Error::FeatureDisabled, and on other platforms
Error::PlatformUnsupported.
On macOS and Windows the preset is the one of the running OS version’s
visual generation. SystemTheme::version_match tells how the running
version relates to it (VersionMatch): macOS 27, which has no preset of
its own yet, gets macos-tahoe as VersionMatch::PresetOlder, and
Windows 10 gets windows-11 as VersionMatch::PresetNewer.
SystemTheme::from_system_with_preset merges over another generation of
the running platform instead. pipeline::platform_preset_name names the
preset without reading the theme, and
pipeline::diagnose_platform_support reports what detection can see.
§Feature flags
No feature is needed to load, merge and resolve presets and TOML files.
Each OS-specific dependency is compiled only on its own target, so
native on macOS pulls in only the macOS dependencies.
| Feature | Enables |
|---|---|
kde, portal, macos, windows | The platform readers above |
linux-kde, linux-portal | Aliases of kde and portal |
linux | linux-kde and linux-portal |
native | linux, macos and windows: every reader |
watch | watch::on_theme_change, for the platforms whose reader feature is on |
material-icons, lucide-icons | The bundled Material Symbols and Lucide icon sets |
system-icons | The platform icon sets: freedesktop icon themes (Linux), SF Symbols (macOS), Segoe Fluent Icons and stock icons (Windows); also enables material-icons |
svg-rasterize | rasterize::rasterize_svg, SVG icons to RGBA through resvg |
system-fonts | fonts::system_face, the platform’s own typeface for a family; on macOS the system UI font’s file through Core Text |
The minimum supported Rust version is 1.88.0.
§Modules
- The crate root:
Theme,ColorMode,SystemTheme,ResolvedTheme,Resolved,ResolutionContext,AccessibilityPreferences,Rgba,ErrorandResult, and frompipelineVersionMatch,PlatformPresetandDiagnosticEntry. prelude: the ten most-used items, for a glob import.theme: the data model, the sparse types and their resolved counterparts, widget by widget.presets:PresetInfo, the description of a bundled preset thatTheme::list_presetsreturns;Theme::presetloads one.resolve: the resolution-time inputs.detect: OS detection: dark mode, reduced motion, accessibility preferences, icon theme and set, desktop environment.icons: the per-set icon loaders, the icon data types and the icon-set choice.fonts: font face matching; the platform’s own typeface with thesystem-fontsfeature.pipeline: the running platform’s preset and a diagnosis of its theme support.errorandcolor: the error and colour types.watch(thewatchfeature): OS theme-change notifications.rasterize(thesvg-rasterizefeature): SVG icons to RGBA.
Re-exports§
pub use color::Rgba;pub use error::Error;pub use pipeline::DiagnosticEntry;pub use pipeline::PlatformPreset;pub use pipeline::VersionMatch;pub use resolve::ResolutionContext;pub use theme::ColorMode;pub use theme::Resolved;pub use theme::ResolvedTheme;pub use theme::Theme;
Modules§
- color
- Color types and sRGB utilities.
- detect
- OS detection: dark mode, reduced motion, accessibility preferences, icon theme and set, desktop environment.
- error
- Error types for theme operations.
- fonts
- Font matching, and the platform’s own typeface for a family.
- icons
- Icon loading.
- kde
- KDE theme reader (the
kdefeature, Linux): maps the kdeglobals INI files to a Theme. - pipeline
- Theme pipeline: reader -> preset merge -> resolve -> validate.
- prelude
- Convenience re-exports for common usage.
- presets
- Bundled theme presets:
PresetInfo, the description of one. - rasterize
- SVG-to-RGBA rasterization utilities.
- resolve
- Theme resolution engine (inheritance + validation).
- theme
- Theme data model: types, defaults, fonts, borders, widgets.
- watch
- Runtime theme change watching.
Structs§
- Accessibility
Preferences - OS-detected accessibility preferences.
- System
Theme - Result of the OS-first pipeline. Holds both resolved variants.
Type Aliases§
- Result
- Convenience Result type alias for this crate.