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 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-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, kcmfonts; 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.