native-theme
What it does
Cross-platform theme data model with 25 semantic color roles, 26 per-widget
themes, and 17 bundled TOML presets. Reads OS themes from KDE Plasma, GNOME
(via xdg-desktop-portal), macOS, and Windows, and produces a fully populated
ResolvedTheme any GUI toolkit can consume.
Theme switching in the showcase application of each connector crate:
gpui

iced

egui

How it fits
Most apps don't depend on this crate directly — they add the connector of their
GUI framework, which pulls native-theme in transitively and re-exports it:
| Your GUI framework | Add this crate |
|---|---|
| gpui | native-theme-gpui |
| iced | native-theme-iced |
| egui | native-theme-egui |
| egui, plus widgets drawn from the theme where egui's own cannot follow it (switch, segmented control, slider, …) | native-theme-egui-widgets, beside native-theme-egui |
| Writing a new framework connector, or using the theme data without one | native-theme, this crate, directly |
Quick start
Add the dependency:
Read the live OS theme:
use SystemTheme;
For OS readers, enable the native feature (or an individual kde / portal
/ macos / windows) — see Feature flags below. No features
are needed to use bundled presets.
Core concepts
-
Theme— sparse, TOML-shaped definition (fields areOption<T>). Load viaTheme::preset(…),Theme::from_toml(…), orTheme::from_file(…). -
ResolvedTheme— one resolved variant, safe to hand to UI code. Every font and every size the model requires has a value, and so does every colour but 61 optional ones. A field the model treats as optional isNonewhere the theme states none:- Colours: most of the 61 are state shades such as
checkbox.hover_background, which a theme, a bundled preset included, may leaveNone. - Sizes: padding sides, menu and list row heights, the menu's least row height, its panel padding and its bar titles' padding, the list header height, toolbar height and item gap, tab item gap and active-indicator width, combobox arrow width, expander arrow gap and content indent, the checkbox's radio indicator width, radio dot diameter and check-mark stroke width, the switch's unchecked thumb diameter. Where one is
Nonethe toolkit's own value applies. - Behaviour:
tooltip.show_delay,dialog.entrance,expander.arrow_side,expander.frame_enabled,tab.active_indicator_sideand the caret's blink (input.caret_blink_on,caret_blink_off,caret_blink_timeout), where the toolkit's own value applies too;defaults.focus_ring_keyboard_only, where unstated a connector draws the focus ring on any focus;defaults.font_whole_pixels, where unstated the font sizes keep their fraction; andtab.active_outward_corner_radius, where unstated the selected tab's feet are square. - Switch outlines: the track and thumb outlines' colours (five of the 61) and widths (
switch.track_border_line_width,switch.thumb_border_line_width); where they areNoneno outline is drawn. A disabled track outline's colour (switch.disabled_unchecked_track_border_color,switch.disabled_checked_track_border_color) leftNonetakes the enabled one. - Slider handle outline: its colours (
slider.thumb_border_color,thumb_hover_border_color,thumb_focus_border_color, three of the 61) and width (slider.thumb_border_line_width); where the width isNonea connector draws its own outline, where it is 0 none. An unset hover or focus colour takes the rest colour. - Caret blink:
input.caret_blink_on_msandcaret_blink_off_msstate a blink together, andcaret_blink_off_ms = 0alone states a caret that does not blink;caret_blink_timeout_msbeside them stops the blinking that long after the last input, the caret shown. A theme that statescaret_blink_on_msor a time-out withoutcaret_blink_off_ms, or acaret_blink_off_msabove 0 withoutcaret_blink_on_ms, fails to resolve,Error::ResolutionIncompletenaming the key to add, so an overlay states both durations: it merges field by field over a preset that may state none. An overlay cannot unset a preset's time-out; to keep the caret blinking it states the largest,caret_blink_timeout_ms = 4294967295(about 49.7 days).
- Colours: most of the 61 are state shades such as
-
SystemTheme— the OS theme, fromSystemTheme::from_system(): both resolved variants (light,dark), the OS's activemode, thepresetthe reader's values were merged over and itsversion_match, the icon set and theme, and the accessibility preferences.pick(mode)gives one variant;with_overlay(…)applies an application's changes. -
ColorMode— theLight/Darkchoice passed when resolving. -
Preset — a named bundled theme. 17 ship today:
- Platform:
kde-breeze,adwaita,windows-11,macos-monterey,macos-tahoe,material-3,ios-13 - Community:
catppuccin-latte,catppuccin-frappe,catppuccin-macchiato,catppuccin-mocha,nord,dracula,gruvbox,solarized,tokyo-night,one-dark
material-3andios-13have no OS reader; an application chooses them as a look.material-3suits any platform, and its Material Symbols icons load with thematerial-iconsfeature.ios-13is a look for desktop apps on macOS: its SF Symbols load only on macOS, so on every other platform, iOS included, its icons areNoneand are never replaced by another set.Enumerate with
Theme::list_presets()orTheme::list_presets_for_platform(). - Platform:
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.
| 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, the fonts and the caret's blink time |
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. On macOS
and Windows without the reader feature it returns Error::FeatureDisabled.
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: 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, under the OS's live
colours, fonts and accessibility settings. pipeline::diagnose_platform_support()
lists what detection can see, for debugging.
Common recipes
Load a bundled preset
use ;
theme.resolve(mode) returns a Resolved wrapper containing variant
(the ResolvedTheme) plus the effective icon-set and icon-theme metadata.
Layer user overrides on a preset
use Theme;
merge fills in only the fields present in the overlay; everything else stays
from the base preset. An overlay needs no name: the base keeps its own. It
changes only the variants it states, so the recipes state both: an overlay of
[light.defaults] alone leaves the dark variant as it was.
Apply an overlay to the OS theme at runtime
use ;
Cheap dark-mode check
use ;
// Cached: the first call reads the OS, later calls return its answer.
if system_is_dark
// Uncached: reads the OS on every call, for polling.
let dark_now = detect_is_dark;
Neither runs the full theme-reader pipeline. system_is_dark() keeps its
answer until detect::invalidate_caches(), so a poll of it never sees the
user switch modes; poll detect_is_dark(), or follow the changes as the next
recipe does.
Watch for OS theme changes
With the watch feature:
use on_theme_change;
Keep the subscription alive: dropping it stops watching.
Icon sets

Semantic icon roles map to platform-appropriate glyphs via typed per-set
loaders. Each loader needs its set's feature and gives None without it:
MaterialLoader needs material-icons and LucideLoader lucide-icons;
the platform loaders need system-icons (which enables material-icons too)
and their platform: FreedesktopLoader Linux, SfSymbolsLoader macOS and
SegoeFluentLoader Windows.
use ;
// Bundled set (no system dependencies).
let copy = new.load;
// System icon theme on Linux: the one the desktop has active.
let sys = new.load;
// A named icon theme instead of the active one.
let breeze_dark = new
.theme
.load;
Animated spinners respect the OS prefers-reduced-motion preference
(MaterialLoader::load_indicator() needs material-icons too):
use MaterialLoader;
use prefers_reduced_motion;
if let Some = load_indicator
Connector crates provide toolkit playback helpers (see the native-theme-gpui and
native-theme-iced READMEs, and native-theme-egui's icons::animated_frame_index and
icons::spin_angle).
Feature flags
[]
= { = "0.7", = ["native"] }
native is a meta-feature enabling every OS reader for the current target
(kde + portal + macos + windows). Individual features:
| Feature | Role |
|---|---|
kde / portal / macos / windows |
Platform-specific theme readers |
linux-kde / linux-portal |
Aliases: kde and portal |
linux |
Meta-feature: linux-kde + linux-portal |
native |
Meta-feature: linux + macos + windows |
watch |
Runtime theme-change notifications (watch::on_theme_change), on the platforms whose reader feature is on |
system-icons |
Platform icon lookups: freedesktop icon themes (Linux), SF Symbols (macOS), Segoe Fluent Icons and stock icons (Windows), each platform's dependencies on that platform only; also enables material-icons |
material-icons / lucide-icons |
Bundle those icon sets |
svg-rasterize |
Rasterise SVG icons to RGBA via resvg |
system-fonts |
The platform's own typeface for a family: fonts::system_face over the system font database (fontdb), and on macOS the system UI font's file through Core Text |
OS-specific dependencies are target-gated — native on macOS only pulls in
macOS-related deps.
The macos reader and the SF Symbols icons need macOS 11 or later: the
reader reads each appearance's colours through
performAsCurrentDrawingAppearance(_:)
and the icons load through
NSImage(systemSymbolName:accessibilityDescription:),
both introduced in macOS 11.0.
The minimum supported Rust version is 1.88.0.
Links
- API reference on docs.rs
- Connectors:
native-theme-gpui,native-theme-iced,native-theme-egui - Showcase examples
- CHANGELOG
License
Licensed under any of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be triple licensed as above, without any additional terms or conditions.