Crate egui_material3 

egui-material3

A comprehensive Material Design 3 component library for egui, providing a complete set of Material Design components with advanced theming support.

Features

• Complete Material Design 3 Components: Buttons, checkboxes, sliders, dialogs, data tables, and more
• Advanced Theming System: Support for light/dark modes, contrast levels, and custom Material Design themes
• Build-time Theme Inclusion: Automatically include theme JSON files at compile time for optimal performance
• Runtime Theme Loading: Load and switch themes dynamically at runtime
• Material Design Icons: Full support for Material Symbols with built-in icon font loading
• Responsive Design: Components adapt to different screen sizes and orientations

Quick Start

Add this to your Cargo.toml:

$ cargo add egui-material3

Basic Usage

use eframe::egui;
use egui_material3::{
    MaterialButton, MaterialCheckbox, MaterialSlider,
    theme::{setup_google_fonts, setup_local_fonts, setup_local_theme,
           load_fonts, load_themes, update_window_background}
};

fn main() -> Result<(), eframe::Error> {
    let options = eframe::NativeOptions {
        viewport: egui::ViewportBuilder::default().with_inner_size([800.0, 600.0]),
        ..Default::default()
    };
     
    eframe::run_native(
        "Material Design App",
        options,
        Box::new(|cc| {
            // Setup Material Design fonts and themes
            setup_google_fonts(Some("Roboto"));
            setup_local_fonts(Some("resources/MaterialSymbolsOutlined.ttf"));
            setup_local_theme(None); // Use default theme
             
            // Load fonts and themes
            load_fonts(&cc.egui_ctx);
            load_themes();
             
            // Apply theme background
            update_window_background(&cc.egui_ctx);
             
            Ok(Box::<MyApp>::default())
        }),
    )
}

#[derive(Default)]
struct MyApp {
    checked: bool,
    slider_value: f32,
}

impl eframe::App for MyApp {
    fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
        egui::CentralPanel::default().show(ctx, |ui| {
            ui.heading("Material Design Components");
             
            // Use Material Design components
            ui.add(MaterialButton::new("Click me"));
            ui.add(MaterialCheckbox::new(&mut self.checked, "Check me"));
            ui.add(MaterialSlider::new(&mut self.slider_value, 0.0..=100.0));
        });
    }
}

Theme System

The theme system supports Material Design 3 with comprehensive theming capabilities:

Build-time Theme Inclusion

Themes can be automatically included at build time from JSON files:

use egui_material3::theme::{setup_local_theme, load_themes};

// Uses themes from resources/ and examples/ directories automatically
setup_local_theme(None);
load_themes();

Runtime Theme Loading

Load custom themes dynamically:

use egui_material3::theme::{setup_local_theme, load_themes};

// Load specific theme file
setup_local_theme(Some("path/to/my-theme.json"));
load_themes();

Theme Modes and Contrast

Support for multiple theme modes and contrast levels:

use egui_material3::theme::{get_global_theme, update_window_background, ThemeMode, ContrastLevel};

// Change theme mode at runtime
if let Ok(mut theme) = get_global_theme().lock() {
    theme.theme_mode = ThemeMode::Dark;
    theme.contrast_level = ContrastLevel::High;
}
// Apply changes
update_window_background(ctx);

Available Components

Basic Components

• MaterialButton - Material Design buttons with multiple variants
• MaterialCheckbox - Checkboxes following Material Design guidelines
• MaterialSlider - Sliders with Material Design styling
• MaterialSwitch - Toggle switches
• MaterialRadio - Radio button groups
• MaterialSelect - Dropdown selection components

Advanced Components

• MaterialChip - Filter and action chips
• MaterialCard2 - Material Design cards
• MaterialDialog - Modal dialogs and alerts
• MaterialFab - Floating Action Buttons
• MaterialProgress - Progress indicators and loading states
• MaterialDataTable - Data tables with sorting and selection

Navigation Components

• MaterialTabs - Tab navigation
• MaterialDrawer - Navigation drawers
• MaterialTopAppBar - App bars and toolbars

Icons and Visual Elements

• MaterialIcon - Material Design icons with font support
• MaterialList - Lists following Material Design patterns
• MaterialImageList - Image lists with online/offline support and smart caching

Image Lists and OnDemand Feature

The MaterialImageList component provides comprehensive image display capabilities:

use egui_material3::image_list;

// Local image files
ui.add(image_list()
    .columns(3)
    .item_spacing(8.0)
    .items_from_paths(glob::glob("resources/*.png")?));

// Online images (requires 'ondemand' feature)
ui.add(image_list()
    .columns(4)
    .item_spacing(8.0)
    .items_from_urls(vec![
        "https://example.com/image1.jpg".to_string(),
        "https://example.com/image2.png".to_string(),
    ]));

// Embedded images from byte arrays
ui.add(image_list()
    .columns(2)
    .item_spacing(8.0)
    .items_from_bytes(vec![
        include_bytes!("image1.png").to_vec(),
        include_bytes!("image2.png").to_vec(),
    ]));

OnDemand Feature

Enable the ondemand feature for online image support:

[dependencies]
egui-material3 = { version = "0.0.6", features = ["ondemand"] }

Key capabilities:

• Smart caching: Downloaded images are cached locally with correct file extensions
• Format detection: Automatically detects PNG, JPEG, GIF, and WebP formats
• Efficient loading: Images are downloaded once and reused from cache
• Performance optimized: UI repaints only when new images are available
• Error handling: Graceful fallback with visual indicators for failed loads

Examples

The crate includes comprehensive examples:

• widget_gallery_example - Showcase of all Material components with theme switching
• nobel_prizes_example - Real-world data table implementation
• stories - Individual component showcase windows for detailed exploration
• package - Standalone example with bundled resources and themes
• ondemand - Image list demonstration with online/offline images and smart caching

Run examples with:

cargo run --example widget_gallery_example
cargo run --example nobel_prizes_example
cargo run --example stories

# OnDemand example with online image support
cd examples/ondemand && cargo run

# Package example runs independently with its own Cargo.toml
cd examples/package && cargo run

Material Design Resources

• Material Design 3
• Material Theme Builder
• Material Design Icons

This crate follows the Material Design 3 specifications and guidelines for consistent, accessible, and beautiful user interfaces.

Re-exports

pub use button::MaterialButton;

pub use button::MaterialButtonVariant;

pub use card2::elevated_card2;

pub use card2::filled_card2;

pub use card2::outlined_card2;

pub use card2::Card2Variant;

pub use card2::MaterialCard2;

pub use checkbox::checkbox;

pub use checkbox::MaterialCheckbox;

pub use chips::assist_chip;

pub use chips::filter_chip;

pub use chips::input_chip;

pub use chips::suggestion_chip;

pub use chips::ChipVariant;

pub use chips::MaterialChip;

pub use datatable::data_table;

pub use datatable::CellContent;

pub use datatable::ColumnWidth;

pub use datatable::DataTableCell;

pub use datatable::DataTableColumn;

pub use datatable::DataTableRow;

pub use datatable::DataTableSource;

pub use datatable::DataTableState;

pub use datatable::DataTableTheme;

pub use datatable::HAlign;

pub use datatable::MaterialDataTable;

pub use datatable::RowAction;

pub use datatable::SortDirection;

pub use datatable::VAlign;

pub use dialog::dialog;

pub use dialog::MaterialDialog;

pub use drawer::dismissible_drawer;

pub use drawer::modal_drawer;

pub use drawer::permanent_drawer;

pub use drawer::standard_drawer;

pub use drawer::DrawerAlignment;

pub use drawer::DrawerHeader;

pub use drawer::DrawerItem;

pub use drawer::DrawerSection;

pub use drawer::DrawerThemeData;

pub use drawer::DrawerVariant;

pub use drawer::MaterialDrawer;

pub use fab::fab_branded;

pub use fab::fab_primary;

pub use fab::fab_secondary;

pub use fab::fab_surface;

pub use fab::fab_tertiary;

pub use fab::google_branded_icon;

pub use fab::FabSize;

pub use fab::FabVariant;

pub use fab::MaterialFab;

pub use fab::SvgIcon;

pub use fab::SvgPath;

pub use icon::icon;

pub use icon::MaterialIcon;

pub use iconbutton::icon_button_filled;

pub use iconbutton::icon_button_filled_tonal;

pub use iconbutton::icon_button_outlined;

pub use iconbutton::icon_button_standard;

pub use iconbutton::icon_button_toggle;

pub use iconbutton::IconButtonVariant;

pub use iconbutton::MaterialIconButton;

pub use imagelist::image_list;

pub use imagelist::masonry_image_list;

pub use imagelist::woven_image_list;

pub use imagelist::ImageListItem;

pub use imagelist::ImageListVariant;

pub use imagelist::MaterialImageList;

pub use layoutgrid::debug_layout_grid;

pub use layoutgrid::layout_grid;

pub use layoutgrid::GridTile;

pub use layoutgrid::GridTileBar;

pub use layoutgrid::MaterialLayoutGrid;

pub use list::list;

pub use list::list_item;

pub use list::ListItem;

pub use list::ListTileStyle;

pub use list::ListTileTitleAlignment;

pub use list::MaterialList;

pub use list::VisualDensity;

pub use menu::menu;

pub use menu::menu_item;

pub use menu::Corner;

pub use menu::FocusState;

pub use menu::MaterialMenu;

pub use menu::MenuBarThemeData;

pub use menu::MenuButtonThemeData;

pub use menu::MenuItem;

pub use menu::MenuStyle;

pub use menu::MenuThemeData;

pub use menu::Positioning;

pub use progress::circular_progress;

pub use progress::linear_progress;

pub use progress::MaterialProgress;

pub use progress::ProgressVariant;

pub use radio::radio;

pub use radio::radio_group;

pub use radio::radio_list_tile;

pub use radio::MaterialRadio;

pub use radio::MaterialRadioGroup;

pub use radio::RadioListTile;

pub use radio::ListTileControlAffinity;

pub use select::select;

pub use select::MaterialSelect;

pub use select::SelectVariant;

pub use select::MenuAlignment;

pub use slider::slider;

pub use slider::range_slider;

pub use slider::MaterialSlider;

pub use slider::MaterialRangeSlider;

pub use slider::RangeValues;

pub use slider::SliderInteraction;

pub use slider::ThumbShape;

pub use snackbar::snackbar;

pub use snackbar::snackbar_with_action;

pub use snackbar::MaterialSnackbar;

pub use snackbar::SnackbarPosition;

pub use snackbar::SnackBarBehavior;

pub use switch::switch;

pub use switch::MaterialSwitch;

pub use tabs::tabs_primary;

pub use tabs::tabs_secondary;

pub use tabs::MaterialTabs;

pub use tabs::TabVariant;

pub use theme::get_global_color;

pub use theme::get_global_theme;

pub use theme::update_global_theme;

pub use theme::ContrastLevel;

pub use theme::MaterialThemeContext;

pub use theme::MaterialThemeFile;

pub use theme::ThemeMode;

pub use topappbar::center_aligned_top_app_bar;

pub use topappbar::large_top_app_bar;

pub use topappbar::medium_top_app_bar;

pub use topappbar::top_app_bar;

pub use topappbar::MaterialTopAppBar;

pub use topappbar::TopAppBarVariant;

Modules

button

card2

checkbox

chips

datatable

dialog

drawer

fab

icon

iconbutton

image_utils

imagelist

Material Design Image Lists

layoutgrid

list

material_symbol

menu

noto_emoji

Noto Emoji Unicode constants — fallback emoji font available in egui.

progress

radio

select

slider

snackbar

switch

tabs

theme

Material Design 3 theming system

topappbar

Structs

TextEdit

A text region that the user can edit the contents of.