Immediate Mode Styling in PanGui

October 22nd, 2025Dev updates

It's been very important to us to make sure that PanGui has a highly capable styling system that can stand toe-to-toe with solutions like CSS.

Styling should easily support things like themes and skins, and it should do a good job of representing context-aware complexity and simplifying the IMGUI side of the code.

Styling should let you detach logic from visuals; every new unique Button implementation should not need different code. You shouldn't be forced to make a ToolbarButton(), TabButton(), LargeButton(), MiniButton(), etc - instead, you should be able to have a single Button() method that can have different visuals and layouting specified by styling.

And last, but not least, styling should solve the problem of default controls. Most IMGUI libraries have a distinctive default visual appearance that's difficult to get away from, because all of the basic controls are implemented using hard-coded visuals that cannot be overridden or extended without essentially reimplementing the entire library of basic controls. We wanted to avoid that kind of situation, which is why - until recently - PanGui had no default controls to speak of.

All of PanGui's built-in controls are now built using the styling system. PanGui will ship with default styles - which may be platform specific, if desired - which implement default visuals for tags like "button" and "toggle". As a result, all built-in controls are completely configurable and extendable by any user. The look of an entire application built using the default controls can easily be changed, simply by loading in another stylesheet.

As you begin reading through the very, very long list of features, you might worry about the performance implications of running such a "complicated" styling system in IMGUI, so we wanted to address that up front. As we created this system, it was extremely important to us that it be fast enough to realistically be used throughout an entire application. It took a lot of iteration, but we believe we've achieved both an incredible feature set, and extremely good IMGUI performance.

It is, of course, unrealistic to make it quite as fast as hard-coded IMGUI code, but we've strived to make the overhead as small as possible. Currently, the styling system is about ~3-5x slower than hard-coding the same visuals and layout. We think we could improve this a little bit more, but for now we are quite pleased with the performance numbers we're getting out of it.

This is also why PanGui's foundational performance and simple architecture is so important. We can afford to offer abstractions like the styling system that add some overhead, because PanGui's core is fast enough that these costs become almost negligible in practice. For a thousand UI elements, whether they are built with styling or not is typically only the difference between the GUI loop taking 0.05 or 0.15 ms.

Finally, we want to emphasize that making use of the styling system is not obligatory to have a "good" development experience with PanGui - making the core IMGUI API excellent is just as important to us. A fundamental part of the design philosophy of PanGui is that it has no preference or bias towards any particular level of abstraction. From working with raw mesh data buffers, to using the IMGUI "node builder" pattern, to using the styling system, to using retained mode patterns - every level of abstraction must be well designed, pleasant to engage with, and blend seamlessly with other levels of abstraction. The user can always choose, for any particular problem, what sort of level they prefer to work at.

But enough talk - let's get to the styling system. We're going to cover the following main points in this post:

• Loading style sheets - Load from strings, resources, or functions.
• Selectors - CSS-like selectors with modifiers, nesting and direct child combinator support.
• Inheritance - #inherit, #inherit-properties, #inherit-selector offer inheritance-like composition capabilities.
• Modifiers - Built-in modifiers (:hover, :hold, :focus) and custom modifiers with per-modifier transitions.
• Variables - Built-in variables like $width, $time and custom variables passed down from immediate mode, animatable through modifiers.
• Shapes - Full SDF shape API with combinations, transforms, and math expressions. Styles define, draw and animate multiple shapes.
• Effects - Support for stacking multiple effects (shadows, gradients, strokes) in order. Overriding and modifying effects is also possible.
• Macros - Pure text-substitution macros with parameter support: @const, @mixin, @style, @shape, @effect
• And much more - There are genuinely too many features and details to cover in a single blog post. We will continue to do more sneak peeks and feature highlights in later development updates, and a full overview will of course be available in the final documentation.

---

Let's start by getting the gist of the styling system, and then afterwards, we'll get into specific features. Here is a basic toggle style, as well as the IMGUI code that uses it.

As you can see, the logic and visuals of the toggle control are completely separate, here; the full appearance and visual behaviour of the toggle is defined through a stylesheet, including animations.

There are a few patterns here that are becoming common for us as we begin to use the styling system.

For example, toggle defines a variable ($tHandleOffset) which is used to control the alpha of the bg-shape's solidColor effect, and the positioning of the handle shape. This variable is then animated using the :enabled modifier, causing the shape and effect to also animate.

An alternate pattern is also on display here, where instead of defining variables that you use to animate shapes, you simply define the target shape directly in the modifier, as is done with :hover here, where the handle shape is expanded by 20px. Any arbitrary shape can mutate into any other arbitrary shape. This approach also works on effects.

Loading style sheets

It's quite simple to load stylesheets. You can provide the style text directly in the code, you can provide a function that provides the text whenever the stylesheet reloads, or you can provide a resource identifier - such as a file-path - which in that case will be loaded by the platform layer.

During IMGUI, you can also swap out stylesheets if need be.

It is also possible to change or add to stylesheets after they've been created. In fact, many of the default platform layer implementations of PanGui provide hot reloading of stylesheet files during development, such that you see the result live in the application as you are editing the stylesheet.

Selectors

Styling supports CSS-like selectors with nesting and direct child combinators.

In C#, the styling "tag hierarchy" used by selectors is then derived from the entering and exiting of style nodes:

Inheritance

Unlike HTML where you can apply multiple classes (for example, <div class="box info-box">), PanGui gives each element only a single identifier (what we call a "tag"). Using inheritance, you can declare the same kind of relationship once in the stylesheet instead of repeating it at every call site:

When you use #inherit, two things happen:

1. Selector matching - The style pretends to be its parent for selector purposes. That is, warning-box matches selectors targeting box.
2. Property copying - All properties from the parent are copied into the child style.

Sometimes you only want one of these behaviors:

You can also inherit, copy from or pretend to be multiple styles:

Modifiers

Built-in modifiers (:hover, :hold, :focus) respond to user interaction automatically. Custom modifiers let you animate any app-specific state. Each modifier defines its own transition duration and easing.

Using modifiers in C# is also quite simple. Exactly like styles, modifiers are also simply tags:

Variables

It is possible to define variables, which can be mutated by modifiers, and which can be used in shape and effect expressions. Variables can be declared inside styles, or in the root stylesheet scope itself, in which case they are global variables.

There are also several built-in variables which can always be used:

• $width: The width of the node
• $height: The height of the node
• $time: The current time in seconds
• $content-width: The width of the node's content
• $content-height: The height of the node's content
• $cursor-position: The screen position of cursor 0

We expect to add more built-in variables over time, as we discover the need for them.

It's also possible to override or provide variables from IMGUI code:

Shapes

To express visuals more complicated than a rectangle, the styling gives you full access to the shapes API, letting you type out shape and math expressions. A style can have as many shapes as you'd like, and shapes can of course be changed by modifiers.

All styles have an implicit shape, bg-shape, which defaults to a simple rect the size of the node. The bg-shape is used to represent the interactive area of the styled node, and is also used to define the area that gets clipped when the clip-content property is true.

Shapes are by default always positioned at the center of the node, but can be moved using the move, move-x and move-y functions.

You can also define reusable shape macros (see the Macros section below).

Available shape functions: circle, rect, roundedRect, arc, pie, triangle, union, intersect, subtract, inverse, expand, move, moveX, moveY, rotate, mix, onion.

Effects

Shapes, by themselves, do nothing. In order for a shape to be displayed, you must create effects, which are lists of graphical effects applied in order to a given shape. Order also matters - effects are applied top to bottom.

You can also define reusable effect macros (see the Macros section below).

The currently available effects are: solidColor, linearGradient, radialGradient, outerShadow, innerShadow and stroke. We expect to add more effects later, such as backdrop blur, glass effects and so on.

Macros

Macros are indicated with @, both at the point of declaration and the point of use. They provide pure text substitution during parsing. There are several distinct macro types: @const for constants, @mixin for reusable style content blocks, @style for generating styles, and @shape and @effect for reusable graphics.

Many macro types also support having parameters, which are simple text snippets that are provided at the point of usage, and substituted into the macro contents before it is parsed.

Macros also support recursive nesting; before a macro is expanded, it will expand any macros it itself contains.

Finally, we've gone to great lengths to be able to provide good and comprehensible error messages when things go wrong with macros, as opaque errors are a common pain point of macros in many languages.

Constants

Constants are, in effect, immutable constant values that are declared ahead of time. They can be used in any expression or property value.

Mixins

Mixins are reusable style content blocks. For example, this is a quick utility for visualizing the structure you're working with, which will draw a single pixel stroke around every styled node inside of a given style:

Mixins can also take parameters, which is very useful for creating reusable appearance "functions":

Style Macros

Style macros are macros for declaring styles. They're great for when you need lots of variations of the same kind of style, with only minor differences.

For example, they're perfect for generating icon styles from font characters:

Usage:

Shape and Effect Macros

Sometimes, you want to use specific kinds of shapes or sets of effects in many different places, perhaps with minor variations. Shape and effect macros are perfect for this.

And much more

We could never cover everything about PanGui's styling system in a single blog post - at least, not without making it several times longer than this one, which is already getting plenty long! But there are a few more minor points we'd like to briefly mention.

Error reporting

For any given language, the user interface is essentially the error reporting system for that language. Syntax errors should explain clearly what is wrong, where it is wrong, and provide suggestions on how to fix it, serving essentially as a teacher and helpful guide.

In addition to its many other features, PanGui's debugger lets you see styling errors as runtime overlays in your application, so you get instant feedback during development. This works especially well with hot reloading of styles.

Debugging

The debugger also has tabs that are very helpful with debugging the style system. For example, you can inspect the layout hierarchy, and see which style properties were applied to a given node, where they came from, and so on - very similar to the view you are presented with when you open the developer tools in a browser.

We will be showing these debugger features off in a future dev update.

All the properties we didn't cover...

• Any property can be animated/changed using modifiers.
• Animate from fit to 200px or any other size type seamlessly, with full wrap support.
• z-index for layering.
• position-type with values: part-of-layout, relative-to-root, relative-to-parent.
• wrap can be set to a number to specify item count per row/column, or to true or 0 for auto-wrapping, or false for no wrapping.
• flow-dir for layout direction, with values: x, y, and eventually x-reverse, y-reverse.
• Typography controls: text-font, text-size, text-color, text-align, text-offset, line-height, text-content including wrapping with word-wrap = no-wrap-and-no-break, no-wrap, word, letter.
• padding, margin, gap with per-side control.
• min-width, max-width, min-height, max-height.
• clip-content for overflow handling.
• Blend modes and color blending with blend-mode and blend-color.
• Multiple size modes: pixels, percentage, ratio, fit, expand.
• Transform properties: translate, scale, scale-pivot, rotation, rotation-pivot.
• Content align: content-align, content-align-x, content-align-y, content-offset, content-offset-x, content-offset-y alignment uses floats (0 to 1) instead of (begin, middle, end), making everything animatable. Centering something is never more complicated than content-align = 0.5.
• spacing for distributing items with values: none, space-around, space-between, space-evenly.
• And more to come!

---

That concludes it for today. We hope you've enjoyed this update on our styling system. It was longer than we intended to make it, really - but there was a lot of ground to cover! Styling is easily the most iterated-upon feature in all of PanGui to date, and it has gone through many versions and reworks before we arrived where we are today.

We're also, of course, interested in hearing what you think about it. If you have thoughts or questions, please join our Discord to join the discussion about PanGui.

All the best,
The PanGui Team