Skip to main content

Crate native_theme

Crate native_theme 

Source
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-3 and ios-13 (the flat look of iOS 13 to 18).
  • Community: catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha, nord, dracula, gruvbox, solarized, tokyo-night and one-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.

PlatformFeatureReadsPreset
KDE Plasmakdekdeglobals; with portal, the portal’s accent colourkde-breeze
GNOME, Budgieportalthe XDG Desktop Portal settings and gsettingsadwaita
macOS 11 and latermacosNSColor under both appearances, NSFont, the scroller style and the accessibility optionsmacos-monterey before 26 (it covers 12 to 15), macos-tahoe from 26
WindowswindowsUISettings, the system metrics and fontswindows-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.

FeatureEnables
kde, portal, macos, windowsThe platform readers above
linux-kde, linux-portalAliases of kde and portal
linuxlinux-kde and linux-portal
nativelinux, macos and windows: every reader
watchwatch::on_theme_change, for the platforms whose reader feature is on
material-icons, lucide-iconsThe bundled Material Symbols and Lucide icon sets
system-iconsThe platform icon sets: freedesktop icon themes (Linux), SF Symbols (macOS), Segoe Fluent Icons and stock icons (Windows); also enables material-icons
svg-rasterizerasterize::rasterize_svg, SVG icons to RGBA through resvg
system-fontsfonts::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

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 kde feature, 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§

AccessibilityPreferences
OS-detected accessibility preferences.
SystemTheme
Result of the OS-first pipeline. Holds both resolved variants.

Type Aliases§

Result
Convenience Result type alias for this crate.