Skip to main content

Crate eframe

Crate eframe 

Source
Expand description

eframe - the egui framework crate

If you are planning to write an app for web or native, and want to use egui for everything, then eframe is for you!

To get started, see the examples. To learn how to set up eframe for web and native, go to https://github.com/emilk/eframe_template/ and follow the instructions there!

In short, you implement App (especially App::update) and then call [crate::run_native] from your main.rs, and/or use eframe::WebRunner from your lib.rs.

§Compiling for web

You need to install the wasm32 target with rustup target add wasm32-unknown-unknown.

Build the .wasm using cargo build --target wasm32-unknown-unknown and then use wasm-bindgen to generate the JavaScript glue code.

See the eframe_template repository for more.

§Simplified usage

If your app is only for native, and you don’t need advanced features like state persistence, then you can use the simpler function [run_simple_native].

§Usage, native:

use eframe::egui;

fn main() {
    let native_options = eframe::NativeOptions::default();
    eframe::run_native("My egui App", native_options, Box::new(|cc| Ok(Box::new(MyEguiApp::new(cc)))));
}

#[derive(Default)]
struct MyEguiApp {}

impl MyEguiApp {
    fn new(cc: &eframe::CreationContext<'_>) -> Self {
        // Customize egui here with cc.egui_ctx.set_fonts and cc.egui_ctx.set_global_style.
        // Restore app state using cc.storage (requires the "persistence" feature).
        // Use the cc.gl (a glow::Context) to create graphics shaders and buffers that you can use
        // for e.g. egui::PaintCallback.
        Self::default()
    }
}

impl eframe::App for MyEguiApp {
   fn ui(&mut self, ui: &mut egui::Ui, frame: &mut eframe::Frame) {
       egui::CentralPanel::default().show_inside(ui, |ui| {
           ui.heading("Hello World!");
       });
   }
}

§Usage, web:

use wasm_bindgen::prelude::*;

/// Your handle to the web app from JavaScript.
#[derive(Clone)]
#[wasm_bindgen]
pub struct WebHandle {
    runner: eframe::WebRunner,
}

#[wasm_bindgen]
impl WebHandle {
    /// Installs a panic hook, then returns.
    #[expect(clippy::new_without_default)]
    #[wasm_bindgen(constructor)]
    pub fn new() -> Self {
        // Redirect [`log`] message to `console.log` and friends:
        eframe::WebLogger::init(log::LevelFilter::Debug).ok();

        Self {
            runner: eframe::WebRunner::new(),
        }
    }

    /// Call this once from JavaScript to start your app.
    #[wasm_bindgen]
    pub async fn start(&self, canvas: web_sys::HtmlCanvasElement) -> Result<(), wasm_bindgen::JsValue> {
        self.runner
            .start(
                canvas,
                eframe::WebOptions::default(),
                Box::new(|cc| Ok(Box::new(MyEguiApp::new(cc))),)
            )
            .await
    }

    // The following are optional:

    /// Shut down eframe and clean up resources.
    #[wasm_bindgen]
    pub fn destroy(&self) {
        self.runner.destroy();
    }

    /// Example on how to call into your app from JavaScript.
    #[wasm_bindgen]
    pub fn example(&self) {
        if let Some(app) = self.runner.app_mut::<MyEguiApp>() {
            app.example();
        }
    }

    /// The JavaScript can check whether or not your app has crashed:
    #[wasm_bindgen]
    pub fn has_panicked(&self) -> bool {
        self.runner.has_panicked()
    }

    #[wasm_bindgen]
    pub fn panic_message(&self) -> Option<String> {
        self.runner.panic_summary().map(|s| s.message())
    }

    #[wasm_bindgen]
    pub fn panic_callstack(&self) -> Option<String> {
        self.runner.panic_summary().map(|s| s.callstack())
    }
}

§Feature flags

  • accesskit (enabled by default) — Enable platform accessibility API implementations through AccessKit.

  • android-game-activity — Enable the game-activity backend via egui-winit on Android

  • android-native-activity — Enable the native-activity backend via egui-winit on Android

  • default_fonts (enabled by default) — If set, egui will use include_bytes! to bundle some fonts. If you plan on specifying your own fonts you may disable this feature.

  • glow — Enable glow for painting, via egui_glow.

    There is generally no need to enable both the wgpu and glow features, but if you do you can pick the renderer to use with [NativeOptions::renderer] and WebOptions::renderer.

  • persistence — Enable saving app state to disk.

  • wayland (enabled by default) — Enables wayland support and fixes clipboard issue.

    If you are compiling for Linux (or want to test on a CI system using Linux), you should enable this feature.

  • web_screen_reader (enabled by default) — Enable screen reader support (requires ctx.options_mut(|o| o.screen_reader = true);) on web.

    For other platforms, use the accesskit feature instead.

  • wgpu (enabled by default) — Enable wgpu for painting (via egui-wgpu).

    There is generally no need to enable both the wgpu and glow features, but if you do you can pick the renderer to use with [NativeOptions::renderer] and WebOptions::renderer.

    Switching from wgpu (the default) to glow can significantly reduce your binary size (including the .wasm of a web app). See https://github.com/emilk/egui/issues/5889 for more details.

    By default, eframe will prefer WebGPU over WebGL, but you can configure this at run-time with WebOptions::wgpu_options.

  • wgpu_no_default_features (enabled by default) — This is exactly like the wgpu feature, but does NOT enable the default features of wgpu and egui-wgpu.

    This means that no wgpu backends are enabled. You will need to enable them yourself, e.g. like this:

    wgpu = { version = "*", features = ["dx12", "metal", "webgl"] }

  • x11 (enabled by default) — Enables compiling for x11.

  • __screenshot — If set, eframe will look for the env-var EFRAME_SCREENSHOT_TO and write a screenshot to that location, and then quit. This is used to generate images for examples.

§Instrumentation

This crate supports using the profiling crate for instrumentation. You can enable features on the profiling crates in your application to add instrumentation for all crates that support it, including egui. See the profiling crate docs for more information.

[dependencies]
profiling = "1.0"
[features]
profile-with-puffin = ["profiling/profile-with-puffin"]

Re-exports§

pub use web::WebLogger;
pub use web::WebRunner;
pub use egui;
pub use egui::emath;
pub use egui::epaint;
pub use egui_glow;
pub use glow;
pub use egui_wgpu;
pub use egui_wgpu::wgpu;
pub use wasm_bindgen;
pub use web_sys;

Modules§

web
egui bindings for web apps (compiling to WASM).

Structs§

CreationContext
Data that is passed to AppCreator that can be used to setup and initialize your app.
Frame
Represents the surroundings of your app.
IntegrationInfo
Information about the integration passed to the use app each frame.
Location
Information about the URL.
WebInfo
Information about the web environment (if applicable).
WebOptions
Options when using eframe in a web page.

Enums§

Error
The different problems that can occur when trying to run eframe.
Renderer
What rendering backend to use.
WebGlContextOption
WebGL Context options

Constants§

APP_KEY
Storage key used for app

Traits§

App
Implement this trait to write apps that can be compiled for both web/wasm and desktop/native using eframe.
Storage
A place where you can store custom data in a way that persists when you restart the app.

Functions§

get_value
Get and deserialize the RON stored at the given key.
set_value
Serialize the given value as RON and store with the given key.

Type Aliases§

AppCreator
This is how your app is created.
Result
Short for Result<T, eframe::Error>.