Proposal: Split widgets from the core library.

[michalsustr]

Thesis

Egui can become more powerful and themeable if it separated widgets/components from the core library.

I'd like to propose a new approach egui could adopt. It is fairly radical, but I think it is radical in the right direction: it reduces the amount of configuration egui needs to carry internally, while making the library more customizable.

I will first motivate an example, then explain the concrete split, then explain why I think this is the right library design approach for egui.

Disclaimer: I've used LLM to pass through and polish the writing.

Motivation

Right now, egui makes the application code beautifully simple:

if ui.button("Delete").clicked() {
    delete_item();
}

This is one of egui's greatest strengths.

Inside that single call, several different concepts are fused together:

• layout
• hit-testing
• pointer/keyboard interaction
• disabled/hover/pressed state
• accessibility semantics
• text measurement
• painting

That coupling is ergonomic for users, but inconvenient for systematic modifications like UI styling.

Consider the following use-case: I would like to make a skeuomorphic design theme, for example like Windows XP. This involves styling many components that should be rendered consistently everywhere. Like a scrollbar:

That sounds like a styling or a theme change. But in practice, implementing this is not merely a theme in the narrow sense of “change the color from gray to blue.” It is also not merely a matter of adding more fields to egui::Style. A Windows XP-style scrollbar has a particular visual grammar, like:

• Non-overlay scrollbar gutter,
• Always visible track, or at least layout-reserving track,
• Raised and sunken 3D bevels,
• Separate arrow buttons at the ends,
• Different visual states for normal, hovered, pressed, disabled,
• Possibly a dotted or gripped center region.

It is quite complex, you get the idea.

But the semantics of the scrollbar are not unusual. It should still scroll the same way, the mouse wheel should work, scroll_to APIs should still work, accessibility should still describe the same thing, and so on.

Egui already has useful style knobs, and proposals like CSS-like styling and per-component styles are useful directions. However doing this with style overrides is not really possible unless we emulate the full richness of CSS, or some equivalent styling language. And this would not come for free. We would pay for it with:

• More configuration structs,
• More fields that every component needs to check,
• More branching in hot UI code,
• More memory usage for style data,
• More invalid states,
• More documentation burden,
• More coupling between components and styling,
• And a styling language that is still less expressive than Rust.

The more expressive the style system becomes, the more it starts to look like a second programming language. But Rust is already a programming language. It is fast, statically checked, optimized by the compiler, and already the language egui users are writing.

So instead of teaching a style struct how to describe every possible scrollbar, I think egui should expose a seam where users can replace the scrollbar implementation itself.

The mind shift one needs to take is that A scrollbar is not a colored rectangle. It is a little program.

This is the case with every other UI components. Trying to describe all of this through a style struct is backwards. You eventually reinvent a slower, incomplete, worse programming language.

Forking, but with a boundary

So what can one do? People who are serious about egui styling already tend to do one of two things: they fork egui, or they reimplement large sets of UI components from scratch.

That sounds bad, because forking usually means you slowly lose contact with upstream. But I do not think the problem is that downstream experimentation exists. The problem is that most libraries are not designed to make downstream experimentation cheap.

Right now, if I want to change a deeply integrated component such as a scrollbar, I have to touch too much. I do not only want to replace a color. I want to replace a small behavior/rendering program while preserving egui's core semantics.

So the goal should not be “make every possible component configurable.”

The goal should be:

Keep the stable semantic substrate upstream, but make the default component implementations replaceable.

This is a much smaller and cleaner problem.

Proposed split

For egui, the natural split could be:

egui-core
egui-components
egui

Where:

egui-core

contains the substrate (what is now egui):

• input
• ids
• responses
• layout
• rects
• shapes
• text rendering
• painting/interaction primitives
• accessibility hooks
• state machinery
• memory
• etc.

And:

egui-components

contains the particular UI components:

• button
• checkbox
• slider
• scrollbar
• text edit
• window
• menu
• combo box
• panels
• etc.

Concretely, this is what should be split away from egui-core:

• component modules (button, checkbox, text edit, image, slider, etc.)
• containers/* (window, scroll area, menu, combo box, panels, popups, etc.)
• grid
• deprecated menu/popup compatibility helpers
• Ui convenience methods that construct concrete components (ui.button, ui.checkbox, ui.menu_button, etc.), moved to extension traits in egui-components

And:

egui

is the compatibility/default facade that gives most users the normal egui experience.

That facade can re-export egui-core and egui-components, so ordinary users can still depend on egui and get the normal batteries-included library.

But the core crate would no longer have component shortcuts like:

ui.button("Delete")

Instead, they belong to the default component pack.

The default experience will be provided by an extension trait:

use egui_components::prelude::*;

if ui.button("Delete").clicked() {
    delete_item();
}

Or the egui facade crate could import/re-export the default component prelude so that normal applications barely notice the split.

But at the architectural level, the important thing is that there is a substrate-only egui where Ui does not know about button.

Ui should know how to allocate space, assign ids, handle input, produce responses, paint shapes, and maintain state. It should not necessarily know what a button looks like.

Where does styling fit in?

This is necessarily not an argument against styling.

Styling is good for ordinary changes, like colors, spacing, rounding, etc. But some changes are not parameter changes. They are implementation changes -- like the scrollbar example I gave. For complex changes like that, the honest representation of the component is code.

This is especially true in egui, because components are already small immediate-mode programs. A component is not a persistent object tree waiting to be styled later. It is code that runs, allocates, interacts, and paints.

So I think the clean design is:

• Use style structs for simple parameterization.
• Use replaceable component code for structural changes.

This reduces complexity, because egui does not need to anticipate every possible future theme. It does not need a giant universal style schema. It does not need to add another option every time someone wants a slightly different button, scrollbar, menu, or slider.

Performance

I think this is also a performance win.

A very expressive styling system is not free. Even if each individual option is cheap, a large style system tends to create costs everywhere:

• more style data to store,
• more options to copy or borrow,
• more branching in components,
• more cache pressure,
• more invalid combinations,
• more code paths,
• more testing,
• more “what does this field mean for this component?” complexity.

And the frustrating part is that even after paying these costs, the style system still will not be expressive enough for all serious customization.

What stays stable

The stable layer should define the contracts custom components must preserve:

• how ids are generated and used,
• how layout is allocated,
• how Response works,
• how focus works,
• how accessibility metadata is attached,
• how scrolling state is represented,
• how pointer and keyboard interaction should behave,
• which invariants components must maintain,
• which pieces of state are semantic rather than visual.

The replaceable layer is the rendering implementation of particular components.

Why this helps third-party components

A split like this also gives the ecosystem a better customization boundary.

Today, if a third-party component internally uses egui's built-in components, the application's theme has only limited control over those internals. If the component uses a scroll area, text edit, combo box, or menu, it tends to inherit egui's default implementation, and only the styling changes can be applied.

With a replaceable component pack, third-party crates can intentionally depend on the component abstraction layer instead of hard-coding a particular visual implementation.

This would not automatically fix all third-party components. Code that implements its own custom scrollbar will still do its own thing. But it gives the ecosystem a clear convention:

Depend on the core semantics and call through the component pack if you want your component to be theme-replaceable.

Then if I want my application to look like Windows XP, I should not need to fork all of egui.

I could fork or replace the component pack:

[patch.crates-io]
egui-components = { path = "../egui-components-winxp" }

Then all components that go through that component pack get the same visual grammar.

Fragmentation

One obvious concern is fragmentation. If components are easier to replace, will the ecosystem split into incompatible egui-like libraries? I think the opposite is more likely.

Today, serious users of egui make their own customization. This pushes people toward forking the whole library or reimplementing whole component sets from scratch. That is existing fragmentation, without a clean boundary.

A core/components split makes the boundary explicit.

It lets experimental component packs exist without forking input handling, layout, painting, accessibility, ids, responses, and all the other hard substrate work.

It also makes upstream egui stronger, because the core becomes the stable shared foundation.

The goal is not to encourage permanent forks. The goal is to make downstream experimentation possible without forking the entire GUI substrate.

Why now?

Historically, this kind of split would have been expensive.

If every user had to understand the internals of egui deeply, then a replaceable-component architecture would be too hard. It would create a lot of burden for both maintainers and users.

But the situation has changed.

Cheap LLMs make library code much easier to inspect, fork, adapt, and keep close to upstream. They are not a replacement for good architecture, but they change the cost model of customization. A design that exposes clear seams is much more valuable now, because users have better tools for working across those seams.

Once you have a well-designed component library that serves as a template for customization, with good reuse of its building blocks, you can point LLM to the library and just tell it what kind of theme customization you'd like to do, and it will do a decent job of it. Most importantly, because of re-use of components internally, you will have a consistent UI change, rather than having to patch-up every component one-by-one.

[ProgramCrafter]

I could fork or replace the component pack:

You don't even need a patch section, you could replace
use egui_components::prelude::*;
with
use egui_components_michalsustr::winxp::*;

[ProgramCrafter]

You are also effectively replacing style settings with generics. While I'm for it in applications I use myself, what of apps which could switch between styles by user's command? Will they need a enum

enum GlobalStyle {
    Winxp,
    Liquidglass,
}

impl GlobalStyle {
    fn button(self, ...) {
        match self {
            Self::Winxp => egui_components::winxp::button(...),
            Self::Liquidglass => egui_components::liguidglass::button(...),
        }
    }
}

writing that, it looks good, and also flexible for sub-UIs which would display another style.

[michalsustr]

@ProgramCrafter agreed for both.

If user wants to have multiple styles in their app (which is probably not a mainstream usecase) they can add a small dispatch boilerplate and pay the fair extra cost (for more code/runtime dispatch etc.)

You are also effectively replacing style settings with generics.

Yes! In a way. But without i) the complicated boilterplate that comes with generics and ii) without having to state all of the things you are generic over. You don't have to reinvent CSS but in Rust generics :)

[michalsustr]

Made a provisional refactor in https://github.com/michalsustr/egui/tree/ms/refactor-egui-components2 see also https://github.com/michalsustr/egui/blob/ms/refactor-egui-components2/PLAN.md

If @emilk / @lucasmerlin like this direction, I can actually make it nicer, and refactor the existing components further to be easily modifiable: split the main logic and rendering into two files, such that users should only modify the rendering files to maintain compatibility. If they modify logic files, they will have to incur their maintainance burden.

Edit: yikes, LLM made shortcuts I did not notice initially, it re-included the separated egui-components. Going through the code, there are lots of code circularities, for example Context::inspection_ui, atomics, and such. But I think it still doable.

[lucasmerlin]

Thanks for the writeup! I've also thought about something like this before (splitting the egui core widgets into a seperate crate).

My biggest concern is the third party widget implementations. I don't think it would work the way you outlined it.
The alternate component libraries would have to remain 100% api-compatible with the core egui components for this to work:

[patch.crates-io]
egui-components = { path = "../egui-components-winxp" }

If the third party component libraries start as a copy of egui-components that might be feasible for a version, but if egui adds new fields or fns in the next version, those would be easily missed. Maybe you could abuse cargo semver-checks to verify these are still compatible, but this still seems like a huge headache.

Also, another big drawback with this would be that it'd be impossible to publish your application to crates.io, since I think patch sections are ignored / stripped during publishing.

---

One big reason to fork egui or make custom widgets was that the default widgets weren't really customizable in what contents you could put inside them. I think we already solved that well with Atoms.

So I think the best way to approach this would be to just allow extending / replacing the painting phase of each widget. I agree that rust code is ultimately the best way to customize the style and behavior of widgets. So maybe we could have some global registry of paint fns for each widget type?

e.g. something like type ButtonPainter = Box<dyn Fn(&Painter, &Button, &Response, SizedAtomLayout)> that you could set via ctx.set_button_painter(..) or something. Could also be a trait defining the methods for all build in widgets.

Combined with the efforts from #3284 that should make egui super customizable, while keeping full compatibility with the ecosystom.

[michalsustr]

Thank you for the nice comments!

The alternate component libraries would have to remain 100% api-compatible with the core egui components for this to work

Yes, and the idea is users let the up-keep to be done by LLMs by pointing them to a changelog. That's exactly how I update egui (or any other rust library) and it basically just works. This would have been impractical before LLMs, but is easy with them, it's exactly the kind of chore work they are best at that would take me long time and is annoying.

Another big drawback with this would be that it'd be impossible to publish your application to crates.io, since I think patch sections are ignored / stripped during publishing.

That's an interesting point I haven't thought of before. I think it's useful to distinguish libraries and applications in this argument:

• Libraries should NOT have changed styling, because that's up to the end user how they want to do it. I think this eliminates most dependants of egui.
• For apps, you could rewrite it as use egui_core instead of use egui and use custom theme prelude.

One big reason to fork egui or make custom widgets was that the default widgets weren't really customizable in what contents you could put inside them. I think we already solved that well with Atoms.

That is not enough for visual grammars, e.g. scrollbar example.

So maybe we could have some global registry of paint fns for each widget type?

One major issue I see with this is it still constrains you in custom themeing when you want to save more information than in the original data structures. As an example, buttons in shadcn theme save a logical variant - I like this approach a lot, because you could write something like

if ui.button("Delete").variant(ButtonVariant::Destructive).clicked() {
    delete_item();
}

in other words, extend the logic of your UI to have consistent visual representation (every destructive operations should be a red button, every create should be a green button, and such).

Finally, the concern

Verifying compatibility [..] still seems like a huge headache

This is not maintenance burden on egui. You do not need to do that, same way how you don't do it now for existing themes people have made. From the point of view of egui library it is just restructuring existing code.

[lucasmerlin]

For apps, you could rewrite it as use egui_core instead of use egui and use custom theme prelude.

That would still mean that published apps could not override the theme used by any third party component libraries they use.

Verifying compatibility [..] still seems like a huge headache

This is not maintenance burden on egui. You do not need to do that, same way how you don't do it now for existing themes people have made. From the point of view of egui library it is just restructuring existing code.

If we don't lay out some easy way this should be done for third party themes, that would probably mean the egui ecosystem would turn into a mess of somewhat-but-not-really compatible 3rd party component crates.

One major issue I see with this is it still constrains you in custom themeing when you want to save more information than in the original data structures. As an example, buttons in shadcn theme save a logical variant - I like this approach a lot, because you could write something like

This should be solvable via #3284 and the classes that already landed. Of course it would not be as strongly-typed as using enums, but you could e.g. define extension traits with your classes, and then use them via button.primary() or button.destructive(). You could access these classes in the custom painter to change the colors.

[michalsustr]

That would still mean that published apps could not override the theme used by any third party component libraries they use.

As mentioned, libraries should not override the themes, only apps. This is the case today, so there is no change.

This should be solvable via #3284 and the classes that already landed.

That's a good point.

If we don't lay out some easy way this should be done for third party themes, that would probably mean the egui ecosystem would turn into a mess of somewhat-but-not-really compatible 3rd party component crates.

Agreed. The way I thought about this is listing the commits in changelog that touch egui-components specifically. Each commit already describes what kind of changes were done. This is not much different to what is being done today, the extra thing is running some bash script that goes through git history between version releases and lists the changes in that directory.

[michalsustr]

I am re-running the split with an LLM and giving it another shot to see roughly how the result could look like.

While doing this, I noticed there are circular references in the code, which make it harder to reason about its structure, as you need to go through a number of files and end up back where you started :)

(personally I try to limit circularity within the scope of single files, when it is needed by the complexity of the domain)

[michalsustr]

There are some blockers for extracting out circularities into another crate than egui-core. These are mostly used in the demo apps/tests, as UI rendering code that has privileged access to egui internals.

Main blockers for extracting circularities

1. Private internals in Context UIs

   • settings_ui/inspection_ui/memory_ui in crates/egui/src/context.rs use private Context::read/write and private internals (ContextImpl, viewport internals, paint stats internals, etc).
   • External crate cannot access those today.

2. Private fields/types in input inspection

   • InputState::ui / PointerState::ui in crates/egui/src/input_state/mod.rs read private fields (touch_states, wheel, zoom_factor_delta, viewport_rect, etc).
   • WheelState and TouchState live in private modules; external crate can’t target them directly.

3. Private memory internals

   • memory_ui references private state types/details (AreaState, internal data bucket types, Memory::interaction() which is pub(crate)).

4. Orphan rule issues for current widget impl style

   • crates/egui/src/introspection.rs has impls like:
     • impl Widget for &epaint::stats::PaintStats
     • impl Widget for &mut epaint::TessellationOptions
   • These cannot be reimplemented in an external crate (trait + type are both foreign).

5. One concrete style API blocker

   • HandleShape::Rect { aspect_ratio } field is private; current UI destructures it in style.rs.
   • External crate cannot do the same without new accessor/mutator API.