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 font DPI, dark mode and icon theme the reader uses, 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, kcmfonts; 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.