/build-gpui-apps

Style

GPUI styles an Element where it is built. The Styled trait supplies chainable methods for layout, spacing, color, borders, and text. Many names deliberately correspond to <a href="https://tailwindcss.com/docs/styling-with-utility-classes" target="_blank" rel="noopener noreferrer">Tailwind CSS utilities</a>: flex items-center gap-2 px-3 becomes .flex().items_center().gap_2().px_3() in Rust. This is a useful way to read and write GPUI layouts, but the values are typed Rust values rather than CSS classes.

use gpui_kit::*;
use gpui_kit::component::ActiveTheme as _;

div()
    .flex()
    .items_center()
    .gap_2()
    .px_3()
    .py_2()
    .bg(cx.theme().background)
    .text_color(cx.theme().foreground)
    .child("Search results")

The builder consumes and returns an element on each call. Rendering can build a fresh tree from current state; persistent application state belongs in an Entity or keyed element state. A style chain describes this frame's presentation, not a stylesheet or a retained component instance. See RenderOnce for frame-local component construction.

Build a first layout

Start with the region that owns the available space, then decide which child has a fixed width and which child can grow. Replace examples/hello_world/src/main.rs with this complete program, then run cargo run -p hello_world from the repository root:

use gpui_kit::*;
use gpui_kit::component::{h_flex, v_flex, ActiveTheme as _};
use gpui_kit::prelude::FluentBuilder as _;

struct StyleExample;

impl Render for StyleExample {
    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        let compact = window.viewport_size().width < px(600.);
        let layout = if compact { v_flex() } else { h_flex() };
        let documents = (1..=60).map(|number| {
            div().p_2().child(format!("Document {number:02}"))
        });

        layout
            .items_stretch()
            .size_full()
            .bg(cx.theme().background)
            .text_color(cx.theme().foreground)
            .child(
                v_flex()
                    .when(!compact, |nav| nav.w_64().flex_shrink_0())
                    .p_3()
                    .gap_2()
                    .child("Navigation")
                    .child("Overview · Documents"),
            )
            .child(
                v_flex()
                    .flex_1()
                    .min_w_0()
                    .min_h_0()
                    .child(h_flex().p_3().child("Documents"))
                    .child(
                        v_flex()
                            .id("document-list")
                            .flex_1()
                            .min_h_0()
                            .overflow_y_scroll()
                            .child(v_flex().p_3().gap_2().children(documents)),
                    ),
            )
    }
}

fn main() {
    gpui_kit::application().run(|cx| {
        gpui_kit::init(cx);
        gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| {
            cx.new(|_| StyleExample)
        })
        .expect("failed to open window");
    });
}

In a wide window, navigation occupies a fixed w_64() rail and the document pane fills the rest. Narrow the content area below 600 logical pixels: the same navigation moves above the document pane, while the document list remains independently scrollable. Scroll to Document 60, then resize the window in both directions. The header stays in place while the list scrolls. This threshold is an explicit Rust condition evaluated when the view renders, not a Tailwind responsive prefix. The navigation in this small exercise is illustrative text; a real application should use reachable navigation controls.

h_flex() makes a row and centers its children on the cross axis. .items_stretch() overrides that default so both panes occupy the row's height. v_flex() makes a column whose children stretch across its width. The fixed navigation pane does not shrink in the wide layout; the document pane takes the remaining width. The scroll area takes the remaining height below the header. The window-sized root gives .size_full() a resolved height; the min_h_0() calls let its flexible descendants shrink into a scroll viewport.

Decide where each size belongs

w_full() and h_full() mean the full available dimension. A percentage height still needs a definite height upstream. Min and max sizes constrain the result; they do not give an otherwise unbounded scroll area a viewport. For a long single-line label in a row, combine .flex_1().min_w_0().truncate() on the label container. .truncate() only changes text overflow; it cannot force an inflexible sibling to give up width.

Choose clipping, scrolling, or positioning

.overflow_hidden() clips content; it does not make that content scrollable. On a stateful element, .overflow_y_scroll() creates vertical scrolling once the element has a bounded height. GPUI Kit's .overflow_y_scrollbar() adds a visible scrollbar and wraps the original element as its scroll area; it is an extension from ScrollableElement, not a Styled method. Keep one owner for each scroll region, and put content padding inside that region if its scrollbar should sit at the pane edge. See Coding Guides for scroll ownership and measurement.

Normal flex children consume layout space. Use .relative() on a container and .absolute().top_0().right_0() on a badge when the badge should overlay content without consuming a row or column slot. Offset setters position an absolute child; they do not make an ordinary flex child absolute. Later siblings normally paint over earlier siblings; general Styled has no z_index(...) method.

Theme and scale

Use semantic colors and radius from cx.theme() for application surfaces. GPUI Kit components already apply their normal theme appearance; style their instances for local layout or an intentional refinement. The named spacing and size helpers are rem based: _1 is 0.25rem, _2 is 0.5rem, _3 is 0.75rem, and _4 is 1rem. In a GPUI Kit Root, the active theme's base font size sets the window rem size, so a font size or zoom change also changes rem based geometry. Use typed setters such as .gap(rems(0.625)) when the scale has no suitable step; reserve px(...) for a dimension that truly needs pixels. See Geometry for length types and Fonts for the theme's rem setup.

Troubleshoot the result

Common Styled methods

GPUI uses underscores where Tailwind uses hyphens. Where a matching concept exists, the first column links to its official Tailwind CSS reference in a new tab. The names are GPUI methods; call them on a Styled value, such as div().gap_2(). These tables cover the distinct Styled operations and the generic setters generated by its macros. Numeric variants follow the families described below, rather than occupying thousands of near-identical rows. Linked pages explain the corresponding styling concept; they do not imply identical behavior in GPUI and a browser.

Display and visibility

Flexbox and Grid

Space and size

Position and overflow

Color and borders

Typography

Effects and cursor

GPUI-specific methods

These APIs have no direct Tailwind utility. Their names remain unlinked so the table does not suggest a false correspondence.

The macros also generate methods for the size (w, h, size, min_size, min_w, min_h, max_size, max_w, max_h), gap (gap, gap_x, gap_y), margin (m, mt, mb, mx, my, ml, mr), padding (p, pt, pb, px, py, pl, pr), and inset (inset, top, bottom, left, right) families. For example, w_64, px_3, and top_0 are real methods. Their shared numeric suffixes are 0, 0p5, 1, 1p5, 2, 2p5, 3, 3p5, every integer from 4 to 12, then 16, 20, 24, 32, 40, 48, 56, 64, 72, 80, 96, 112, and 128. They also include _px, _full, and fractional suffixes such as _1_2; only families that accept auto generate _auto. Non-auto values also have _neg_ forms, such as mt_neg_2. Border sides (border, border_t, border_b, border_l, border_r, border_x, border_y) have pixel-width suffixes 0 through 12, plus 16, 20, 24, and 32. Rounded sides and corners use none, xs, sm, md, lg, xl, 2xl, 3xl, and full. Use these mechanically generated names only when the resulting property makes sense for the layout.

Spacing helpers use a rem based scale: _1 is 0.25rem, _2 is 0.5rem, _3 is 0.75rem, and _4 is 1rem. For a value outside the named helpers, use a typed setter such as .gap(rems(0.625)), .w(px(240.)), or .w(relative(0.5)). relative(0.5) expresses half the available relative size; px(...) expresses pixels. The named scale and method set are GPUI's implementation, so check the actual API rather than assuming every Tailwind class exists.

What a style call changes

Every Styled element exposes fn style(&mut self) -> &mut StyleRefinement. A call such as .px_3() writes the relevant optional padding fields; .bg(...) writes the background field. Fields left unset do not replace existing values when refinements are merged. The resolved Style holds both layout data and presentation data.

Styled calls → StyleRefinement → resolved Style
                                    ├─ layout fields → Taffy → bounds
                                    └─ color, text, shadow, cursor → GPUI paint and interaction

In an element's request_layout phase, GPUI passes layout fields such as display, size, padding, gap, flex alignment, position, and grid placement, together with child layout IDs, to Taffy. Taffy computes the geometry. GPUI then uses the bounds in prepaint and the Paint phase for drawing and hit testing. Taffy does not implement GPUI's text shaping, hover listeners, Actions, or painting.

StyleRefinement itself implements Styled, so a state style closure can use the same utility methods. Interaction variants such as .hover(|style| style.bg(...)) belong to InteractiveElement, and need an interactive element. Conditional builder calls are different: .when(...) chooses a chain step while this frame is built.

Fluent composition and trait boundaries

The fluent surface combines several traits. Styled supplies style methods. ParentElement supplies .child(...). InteractiveElement supplies .id(...), returning a Stateful<Div> that supports identity dependent methods such as .overflow_y_scroll(). InteractiveElement also supplies state style refinements such as .hover(...). Every IntoElement implements FluentBuilder; IntoElement alone does not grant styling, children, or interaction. If a method is missing, check the receiver's trait and whether a preceding call changed its type.

use gpui_kit::*;
use gpui_kit::component::ActiveTheme as _;

div()
    .id("result-row")
    .px_3()
    .py_2()
    .when(selected, |row| row.bg(cx.theme().selection))
    .when_some(subtitle, |row, text| row.child(text))
    .child(title)

Conditional closures consume and return the builder. The condition is evaluated during the current render; it is not a subscription. .map(...) can return a different type. Use an Entity to own state that changes across frames.

For example, .when(selected, ...) evaluates selected while building this frame; .hover(|style| ...) installs a style refinement for pointer hover. A scroll call needs a stateful element, so give the intended scroll owner an .id(...) first. An arbitrary component implementing IntoElement cannot be assumed to accept .child(...) or .bg(...); inspect its own builder API or wrap it in a div() that owns those styles.

GPUI Kit adds StyledExt for neutral helpers such as h_flex, v_flex, and refine_style, and ThemeStyled for theme driven appearance such as popover_style(cx). These are extensions on top of GPUI's Styled, not Tailwind utilities. When implementing a custom element, return its StyleRefinement from style() and apply the resolved style during layout and paint. Implement only the child and interaction traits that the element can actually support.

The correspondence with Tailwind is deliberately scoped: there are no CSS selectors, cascade, responsive prefixes, or promise that every Tailwind utility has a GPUI method. Use GPUI's typed layout helpers for geometry, GPUI Kit theme tokens for product appearance, and explicit element or entity APIs for behavior.

Documentation license: original prose and illustrations for which GPUI Kit holds licensing rights are also offered under CC BY 4.0. When copying or adapting, credit GPUI Kit, link the source (https://gpui-kit.com/docs/style) and https://creativecommons.org/licenses/by/4.0/, and indicate changes. Code examples and software source use Apache-2.0; third-party material retains its terms; existing Apache-2.0 permissions remain.

Bundled from GPUI Kit. Documentation prose: CC BY 4.0; code examples: Apache-2.0. Changes: documentation links localized, asset URLs made absolute, and this attribution added.