egui

# 🖌 egui: an easy-to-use GUI in pure Rust [](https://github.com/emilk/egui)
egui (pronounced "e-gooey") is a simple, fast, and highly portable immediate mode GUI library for Rust. egui runs on the web, natively, and [in your favorite game engine](#integrations). egui aims to be the easiest-to-use Rust GUI library, and the simplest way to make a web app in Rust. egui can be used anywhere you can draw textured triangles, which means you can easily integrate it into your game engine of choice. [`eframe`](https://github.com/emilk/egui/tree/main/crates/eframe) is the official egui framework, which supports writing apps for Web, Linux, Mac, Windows, and Android. ## Example ``` rust ui.heading("My egui Application"); ui.horizontal(|ui| { ui.label("Your name: "); ui.text_edit_singleline(&mut name); }); ui.add(egui::Slider::new(&mut age, 0..=120).text("age")); if ui.button("Increment").clicked() { age += 1; } ui.label(format!("Hello '{name}', age {age}")); ui.image(egui::include_image!("ferris.png")); ```     ## Sections: * [Example](#example) * [Quick start](#quick-start) * [Demo](#demo) * [Goals](#goals) * [State / features](#state) * [Dependencies](#dependencies) * [Who is egui for?](#who-is-egui-for) * [Integrations](#integrations) * [Why immediate mode](#why-immediate-mode) * [FAQ](#faq) * [Other](#other) * [Credits](#credits) ([egui 的中文翻译文档 / chinese translation](https://github.com/Re-Ch-Love/egui-doc-cn/blob/main/README_zh-hans.md)) ## Quick start There are simple examples in [the `examples/` folder](https://github.com/emilk/egui/blob/main/examples/). If you want to write a web app, then go to and follow the instructions. The official docs are at . For inspiration and more examples, check out [the egui web demo](https://www.egui.rs/#demo) and follow the links in it to its source code. If you want to integrate egui into an existing engine, go to the [Integrations](#integrations) section. If you have questions, use [GitHub Discussions](https://github.com/emilk/egui/discussions). There is also [an egui discord server](https://discord.gg/JFcEma9bJq). If you want to contribute to egui, please read the [Contributing Guidelines](https://github.com/emilk/egui/blob/main/CONTRIBUTING.md). ## Demo [Click to run egui web demo](https://www.egui.rs/#demo) (works in any browser with Wasm and WebGL support). Uses [`eframe`](https://github.com/emilk/egui/tree/main/crates/eframe). To test the demo app locally, run `cargo run --release -p egui_demo_app`. The native backend is [`egui-wgpu`](https://github.com/emilk/egui/tree/main/crates/egui-wgpu) (using [`wgpu`](https://crates.io/crates/wgpu)) and should work out-of-the-box on Mac and Windows, but on Linux you need to first run: `sudo apt-get install -y libclang-dev libgtk-3-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev` On Fedora Rawhide you need to run: `dnf install clang clang-devel clang-tools-extra libxkbcommon-devel pkg-config openssl-devel libxcb-devel gtk3-devel atk fontconfig-devel` **NOTE**: This is just for the demo app - egui itself is completely platform agnostic! ## Goals * The easiest to use GUI library * Responsive: target 60 Hz in debug build * Friendly: difficult to make mistakes, and shouldn't panic * Portable: the same code works on the web and as a native app * Easy to integrate into any environment * A simple 2D graphics API for custom painting ([`epaint`](https://docs.rs/epaint)). * Pure immediate mode: no callbacks * Extensible: [easy to write your own widgets for egui](https://github.com/emilk/egui/blob/main/crates/egui_demo_lib/src/demo/toggle_switch.rs) * Modular: You should be able to use small parts of egui and combine them in new ways * Safe: there is no `unsafe` code in egui * Minimal dependencies egui is *not* a framework. egui is a library you call into, not an environment you program for. **NOTE**: egui does not claim to have reached all these goals yet! egui is still work in progress. ### Non-goals * Become the most powerful GUI library * Native looking interface ## State egui is in active development. It works well for what it does, but it lacks many features and the interfaces are still in flux. New releases will have breaking changes. Still, egui can be used to create professional looking applications, like [the Rerun Viewer](https://app.rerun.io/). ### Features * Widgets: label, text button, hyperlink, checkbox, radio button, slider, draggable value, text editing, color picker, spinner * Images * Layouts: horizontal, vertical, columns, automatic wrapping * Text editing: multiline, copy/paste, undo, emoji supports * Windows: move, resize, name, minimize and close. Automatically sized and positioned. * Regions: resizing, vertical scrolling, collapsing headers (sections), panels * Rendering: Anti-aliased rendering of lines, circles, text and convex polygons. * Tooltips on hover * Accessibility via [AccessKit](https://accesskit.dev/) * Label text selection * And more! Check out the [3rd party egui crates wiki](https://github.com/emilk/egui/wiki/3rd-party-egui-crates) for even more widgets and features, maintained by the community. Light Theme: ## Dependencies `egui` has a minimal set of default dependencies. Heavier dependencies are kept out of `egui`, even as opt-in. All code in `egui` is Wasm-friendly (even outside a browser). To load images into `egui` you can use the official [`egui_extras`](https://github.com/emilk/egui/tree/main/crates/egui_extras) crate. [`eframe`](https://github.com/emilk/egui/tree/main/crates/eframe) on the other hand has a lot of dependencies, including [`winit`](https://crates.io/crates/winit), [`image`](https://crates.io/crates/image), graphics crates, clipboard crates, etc, ## Who is egui for? egui aims to be the best choice when you want a simple way to create a GUI, or you want to add a GUI to a game engine. If you are not using Rust, egui is not for you. If you want a GUI that looks native, egui is not for you. If you want something that doesn't break when you upgrade it, egui isn't for you (yet). But if you are writing something interactive in Rust that needs a simple GUI, egui may be for you. ## Integrations egui is built to be easy to integrate into any existing game engine or platform you are working on. egui itself doesn't know or care on what OS it is running or how to render things to the screen - that is the job of the egui integration. An integration needs to do the following each frame: * **Input**: Gather input (mouse, touches, keyboard, screen size, etc) and give it to egui * Call into the application GUI code * **Output**: Handle egui output (cursor changes, paste, texture allocations, …) * **Painting**: Render the triangle mesh egui produces (see [OpenGL example](https://github.com/emilk/egui/blob/main/crates/egui_glow/src/painter.rs)) ### Official integrations These are the official egui integrations: * [`eframe`](https://github.com/emilk/egui/tree/main/crates/eframe) for compiling the same app to web/wasm and desktop/native. Uses `egui-winit` and `egui_glow` or `egui-wgpu` * [`egui_glow`](https://github.com/emilk/egui/tree/main/crates/egui_glow) for rendering egui with [glow](https://github.com/grovesNL/glow) on native and web, and for making native apps * [`egui-wgpu`](https://github.com/emilk/egui/tree/main/crates/egui-wgpu) for [wgpu](https://crates.io/crates/wgpu) (WebGPU API) * [`egui-winit`](https://github.com/emilk/egui/tree/main/crates/egui-winit) for integrating with [winit](https://github.com/rust-windowing/winit) ### 3rd party integrations Check the wiki to find [3rd party integrations](https://github.com/emilk/egui/wiki/3rd-party-integrations) and [egui crates](https://github.com/emilk/egui/wiki/3rd-party-egui-crates). ### Writing your own egui integration Missing an integration for the thing you're working on? Create one, it's easy! See . ## Why immediate mode `egui` is an [immediate mode GUI library](https://en.wikipedia.org/wiki/Immediate_mode_GUI), as opposed to a *retained mode* GUI library. The difference between retained mode and immediate mode is best illustrated with the example of a button: In a retained GUI you create a button, add it to some UI and install some on-click handler (callback). The button is retained in the UI, and to change the text on it you need to store some sort of reference to it. By contrast, in immediate mode you show the button and interact with it immediately, and you do so every frame (e.g. 60 times per second). This means there is no need for any on-click handler, nor to store any reference to it. In `egui` this looks like this: `if ui.button("Save file").clicked() { save(file); }`. A more detailed description of immediate mode can be found [in the `egui` docs](https://docs.rs/egui/latest/egui/#understanding-immediate-mode). There are advantages and disadvantages to both systems. The short of it is this: immediate mode GUI libraries are easier to use, but less powerful. ### Advantages of immediate mode #### Usability The main advantage of immediate mode is that the application code becomes vastly simpler: * You never need to have any on-click handlers and callbacks that disrupts your code flow. * You don't have to worry about a lingering callback calling something that is gone. * Your GUI code can easily live in a simple function (no need for an object just for the UI). * You don't have to worry about app state and GUI state being out-of-sync (i.e. the GUI showing something outdated), because the GUI isn't storing any state - it is showing the latest state *immediately*. In other words, a whole lot of code, complexity and bugs are gone, and you can focus your time on something more interesting than writing GUI code. ### Disadvantages of immediate mode #### Layout The main disadvantage of immediate mode is it makes layout more difficult. Say you want to show a small dialog window in the center of the screen. To position the window correctly the GUI library must first know the size of it. To know the size of the window the GUI library must first layout the contents of the window. In retained mode this is easy: the GUI library does the window layout, positions the window, then checks for interaction ("was the OK button clicked?"). In immediate mode you run into a paradox: to know the size of the window, we must do the layout, but the layout code also checks for interaction ("was the OK button clicked?") and so it needs to know the window position *before* showing the window contents. This means we must decide where to show the window *before* we know its size! This is a fundamental shortcoming of immediate mode GUIs, and any attempt to resolve it comes with its own downsides. One workaround is to store the size and use it the next frame. This produces a frame-delay for the correct layout, producing occasional flickering the first frame something shows up. `egui` does this for some things such as windows and grid layouts. The "first-frame jitter" can be covered up with an extra _pass_, which egui supports via `Context::request_discard`. The downside of this is the added CPU cost of a second pass, so egui only does this in very rare circumstances (the majority of frames are single-pass). For "atomic" widgets (e.g. a button) `egui` knows the size before showing it, so centering buttons, labels etc is possible in `egui` without any special workarounds. See [this issue](https://github.com/emilk/egui/issues/4378) for more. #### CPU usage Since an immediate mode GUI does a full layout each frame, the layout code needs to be quick. If you have a very complex GUI this can tax the CPU. In particular, having a very large UI in a scroll area (with very long scrollback) can be slow, as the content needs to be laid out each frame. If you design the GUI with this in