/build-gpui-apps

API Reference

An inventory of the script surface: what exists, and which module it comes from. The other pages explain why each thing works the way it does — this one is for looking a name up.

The authority is not this page. The runtime generates gpui-kit.d.ts for its own version and refreshes it beside your source when the application loads. That refresh is best-effort; gpui-shell types <directory> performs the same write and reports a failure. The generated header names the gpui-shell version and includes that application's HostModule registrations. Keep the file ignored, and put // @ts-check at the top of a script to have an editor check against it. The manifest's Git dependencies are not listed here either: they are linked into node_modules by the same refresh, and their names, signatures and documentation come from the packages themselves. See Dependencies.

The modules

Each built-in module names the public Rust layer it exposes, so an import says which layer a script depends on. The gpui-kit module also carries the shell bridge needed to use GPUI from JavaScript: Views, retained entities, scheduling and shared types. gpui is a compatibility alias for this module and exposes the same bindings, including div.

import { View, div } from "gpui-kit";
import { div as gpuiDiv } from "gpui";
import { Button, v_flex } from "gpui-base";
import { fps_monitor } from "gpui-fps";

Two names are never imported, for two different reasons. window is a real global: nothing hands it to you, it is simply in scope. cx is the opposite — it is never a global, and only ever arrives as an argument: render(cx), init(props, cx), the second argument of every handler, the parameter of a cx.spawn body. The standard-runtime modules — fs/promises, path, crypto, process, net, websocket and the rest — are gated by the host's grant and are documented in Capabilities.

API shape follows the Rust original: a method on App is a method on cx, a method on Window is on the window global, an associated constructor is Type.new(...), and a free function stays lowercase. Names with no direct GPUI or Base original belong to the module for the layer that implements them. Type-only names appear in these tables too, but are never run-time values.

The gpui-kit module

Elements

PathBuilder.fill() and .stroke(width) return a handle that chains move_to, line_to, curve_to, cubic_bezier_to, arc_to, add_polygon, close and dash_array, and ends in build(). Paint the result with window.paint_path(path, background) — the one element constructor reached through an object, because the thing it mirrors is a method on the window.

list and uniform_list are GPUI's own lazy lists and take (id, item_count, get_key, render), the shape of gpui-base's v_virtual_list without its item_sizes: no sizes, because GPUI measures the items itself. uniform_list measures one row and places every row by it, so render(range, cx) returns one element per item in the range as a virtual list's does. list measures each item it draws and keeps the sizes, so render(index, cx) returns one element for one item, and rows — or panels — of unequal height need not say how tall they are. Both draw only what is on screen plus a short band past the fold, scroll themselves, and pair with a Scrollbar by name; neither takes a VirtualListScrollHandle.

A string is an element too, exactly as &str implements IntoElement in GPUI: .child("hello") is how text is written, and the style comes from the element holding it.

Views

A subclass defines init?(props, cx), which runs once, and render(cx), which returns one Element, Entity or string and runs when the View is invalidated. An optional update(props) runs when a parent changes a nested View's props.

Scheduling

Focus

Shared types

FocusHandle

Created with cx.focus_handle(), handed to an element with track_focus(handle), and released with release().

The gpui-shell module

These are type-only concepts introduced by the JavaScript bridge itself. Import them only for type checking; the module has no run-time values.

ScopePhase describes which shell call owns the current Context. It is unrelated to GPUI's DispatchPhase, which controls capture and bubble ordering during event dispatch.

The cx context

There are two context lifetimes with the same methods. Context, received by render and event handlers, belongs to that host call; retaining it beyond the call, including across an await, reports a stale-context error. AsyncContext, described below, is the flavour intended to survive an await.

Several of these name the GPUI method they mirror: open_url is App::open_url, read_from_clipboard and write_to_clipboard are App::read_from_clipboard and App::write_to_clipboard, focus_handle is App::focus_handle (GPUI has no FocusHandle::new, and neither does this), new is AppContext::new, and spawn is App::spawn.

AsyncContext

AsyncContext extends Context and adds no members. The difference is lifetime, not surface: an ordinary Context speaks for one host call and reports clearly once that call has returned, while an AsyncContext names no call at all — it resolves whichever is running when a member is used, and refuses only when none is. It is the mirror of GPUI's AsyncApp.

Three places hand one out: init, the body of cx.spawn, and the callbacks of cx.timer. Those are the three whose job is to set up or continue work that outlives the call it was started from.

The window global

The global has the Window type exported by gpui-kit. Nothing hands it to you and there is nothing to import at the call site. Every call reads the host call that is running now and throws outside one, so there is no handle to hold and nothing that can go stale. An overlay belongs to the window rather than to the View that opened it, which is why these are here and not on Context.

The measurements — everything from rem_size() down to is_maximized() — are legal from render, because a View that sizes itself from the window has to ask during the pass that draws it. Everything that changes the window is refused there, for the reason cx.notify() is: a frame that changes the window it is drawing into is a frame arguing with itself.

open_dialog, open_sheet and open_sheet_at take a function returning an element, not an element: a dialog outlives the call that opened it, and the function runs again whenever it redraws. Everything here except the two has_active_* queries and paint_path is illegal from render. See Overlays.

Storage

The Web Storage API, unchanged. Both stores are also bare globals — localStorage.getItem(k) and window.localStorage.getItem(k) are the same call — because that is true in a browser too.

Values are strings, so structure goes through JSON.stringify and JSON.parse exactly as it would on the web. flush() is the one addition: a browser never needs it, because its storage is synchronous all the way down. localStorage is capability-gated and throws when the host did not grant it; sessionStorage never is, because nothing it holds leaves the process. See Capabilities.

The gpui-base module

The components here own behavior, focus and what a screen reader hears, and draw next to nothing themselves. The picture is the script's, written with the style surface. Each name links to the component's own page in the gpui-base documentation, which is where its full Rust surface and its behavior are described.

Layout

Controls

All four slider parts take the same SliderState, and all four are needed — a slider with no SliderIndicator cannot be moved at all.

Text editing

There is no numeric state type: an InputState becomes a number state by being given set_step, set_min and set_max.

Containers and overlays

Two gaps are worth knowing before you build on these: arrow-key navigation of an open Select or Combobox list is yours to wire (the pieces are there — see below), and Enter and Escape do not reach a DatePicker. Both are described where they bite, in the declarations for each type.

Tables and lists

Both virtual lists take (id, item_count, item_sizes, get_key, render). render(range, cx) is the only callback in this API that the host calls during a frame, which is why handlers, retained state and cx.notify() are all refused inside it.

Dock

The area's methods are add_panel(view, options), remove_panel(id), panels(), dump(), load(state), has_dock, is_dock_open, toggle_dock, remove_dock, dock_size, set_dock_size, set_dock_collapsible, is_locked, set_locked, is_zoomed, zoom_out, on("layout_changed", handler) and release().

Every edit is applied once the call that made it has returned, in the order the calls were made — a panel's body comes from cx.new(Class), which is still being constructed — so panels() and dump() read the layout as it was before this turn's edits. See Dock and Panels.

Retained handles

Each is created once — in init or an event handler, never in render — and every one of them has release(): boolean, which returns whether it was still live. Using a handle after releasing it throws.

on(...) replaces the handler for that event rather than adding a second one, and answers whether there was one before.

InputState

From InputState.new(options?), where options is { placeholder?: string, value?: string }.

TextareaState

From TextareaState.new(options?), where options is { placeholder?: string, value?: string, rows?: number }.

SliderState

From SliderState.new(options?), where options is { min?, max?, step?, scale?: "linear" | "logarithmic", value?: SliderValue }. The defaults are 0..100 in steps of 1, starting at min. A "logarithmic" scale needs a min above zero.

OtpState

From OtpState.new(length, options?), where options is { value?: string, masked?: boolean }. The length is fixed at creation.

VirtualListScrollHandle

From VirtualListScrollHandle.new(), handed to a list with track_scroll(handle).

Calendar

CalendarState exists for month_days() — which dates fall in which week, where the neighbouring months' days go, and how many weeks this month needs. You draw the cells.

const grid = this.calendar.month_days()[0];
v_flex().children(
  grid.map((week) =>
    h_flex().children(
      week.map((day) =>
        Button.new(day)
          .selected(day === this.calendar.value())
          .on_click((_, cx) => {
            this.calendar.set_value(day);
            cx.notify();
          })
          .child(String(Number(day.slice(8)))),
      ),
    ),
  ),
);

Base's Calendar element is not bound, and that is a decision rather than an omission: it walks the same grid calling a renderer once per cell — up to forty-two crossings into JavaScript per frame, from inside GPUI's layout pass, for cells that carry no behavior. Reading the grid here and drawing it yourself is the same work without them.

Dates are "YYYY-MM-DD": sorting them as text sorts them by time, and new Date(s) reads one — which is where a weekday name or a localized month label comes from.

Theme

Reading the theme is cx.theme(). set_theme remains in gpui-base because the theme belongs to that layer. Mutation still requires a live host call and is legal only from an event handler or task, never from render or layout.

Other types

Composition patterns

Five of these components are not one element but an arrangement, and the tables above cannot say so. Each snippet below is the smallest thing that works; all of them were checked against the runtime.

A controlled control. Checkbox, Switch, Radio and Toggle hold no state: you read the value in and write it back out. Nothing is drawn for you, so the indicator is a child.

Checkbox.new("done")
  .checked(this.checked)
  .on_change((checked, cx) => {
    this.checked = checked;
    cx.notify();
  })
  .child(this.checked ? "done" : "not done");

Progress announces; the bar is yours. The root carries the role and the 0..=100 a screen reader reads, and draws nothing at all.

Progress.new("upload")
  .value(62)
  .child(
    ProgressTrack.new()
      .w(200)
      .h(6)
      .bg(cx.theme().colors.muted)
      .child(ProgressIndicator.new().w(124).h(6).bg(cx.theme().colors.primary)),
  );

A slider is four parts, and all four are needed — a slider with no SliderIndicator cannot be moved, because that is the box every pointer position is measured against. All four take the same state.

Slider.new(this.volume).child(
  SliderTrack.new(this.volume)
    .w(200)
    .h(16)
    .child(SliderIndicator.new(this.volume).h(4).bg(cx.theme().colors.primary))
    .child(
      SliderThumb.new(this.volume).w(12).h(12).bg(cx.theme().colors.background),
    ),
);

Select owns the keyboard, Popup owns the surface. The root holds the combobox role and the open state; the list is a Popup inside it. It needs two focus handles — one for the trigger, one for the content — and without the first nothing on screen has the keyboard.

Select.new("mode")
  .accessibility_label("Mode")
  .open(this.open)
  .track_focus(this.trigger)
  .content_focus_handle(this.list)
  .on_open_change((open, cx) => {
    this.open = open;
    cx.notify();
  })
  .child(
    Popup.new("mode-list", trigger)
      .anchor("bottom_left")
      .when(this.open, (el) => el.content(list)),
  );

Arrow-key navigation of an open list is yours to write: base expects whatever is inside to run the highlight from its own key bindings, and nothing does that for you. The pieces are here — put on_key_down on the content element the keyboard was moved to, or bind ↑ / ↓ to actions under a key_context of your own. Out of the box the pointer works, Escape closes, Enter and ↓ open, and the highlight does not move.

A virtual list and its scrollbar are paired by name. The list paints no bar of its own, and nothing checks the pairing before it runs, so both halves are needed.

v_flex()
  .relative()
  .h(200)
  .child(
    v_virtual_list(
      "rows",
      rows.length,
      28,
      (index) => rows[index].id,
      (range) =>
        rows.slice(range.start, range.end).map((row) => div().child(row.name)),
    ).size_full(),
  )
  .child(Scrollbar.vertical("rows").absolute().inset_0());

A nested View is created once and mounted as a child. cx.new belongs in init or an event handler; the entity is a child wherever a child is taken.

init(props, cx) {
  this.chart = cx.new(PriceChart, { symbol });
}
render() {
  return v_flex().child(this.chart);
}

The gpui-fps module

Its parent must be relative(). The HUD owns its own presentation; ordinary styles and children do not apply to it.

Element methods

Every element shares one prototype, so every method below type-checks on every element — which component a method actually suits is not expressed by the types. A behavior builder handed to a component that does not honour it is reported in the log rather than dropped in silence.

Element builder methods answer the same element, so a chain is one expression. map is the exception: like GPUI's FluentBuilder.map, it returns exactly what its callback returns. An element is consumed when it is used as a child and belongs to the render pass that built it.

Composition

Slots

A slot is not a child: the element is consumed by the component and rendered where the component decides.

Events

Actions and key bindings

An action is the level above a keystroke. cx.bind_keys says which chord means "save", in which context; on_action("save", ...) on an element says what "save" does. A menu item or a toolbar button dispatching the same name through window.dispatch_action("save") reaches the same handler, and neither end has to know about the other.

init(_props, cx) {
  cx.bind_keys([{ keystroke: "cmd-s", action: "save", context: "Editor" }]);
}

render(_cx) {
  return div()
    .key_context("Editor")
    .track_focus(this.handle)
    .on_action("save", (event, cx) => this.save(cx));
}

context is a predicate matched against the key_context(...) an element declares, so one chord can mean one thing in a list and another in an editor. Registering several on_actions on one element is fine and they are independent; an action none of them claims carries on to an element further out.

That group — on_key_down, on_key_up, the four pointer handlers, on_action and key_context — is wired on div, h_flex, v_flex, Button, Link, Checkbox, Switch, Radio, Toggle, Tabs and Tab. On any other component the handler is recorded and never reaches GPUI, and the log says so — wrap it and write the handler on the wrapper.

Wired is not the same as reachable. A key travels the focus path, so a component that accepts no focus handle — Tab — hears presses and never hears keys, however well both are wired.

Control state

Accessibility

Focus and keyboard

Scrolling and panels

Anchored surfaces

Dock commands

What an element a dock's chrome drew does. A cached chrome description has no script event-handler lifetime, so it may not register one — a command carries no script value instead, and base does the work. Every one takes the object its handler was given as its first argument, and they belong on a div, an h_flex or a v_flex.

Dock chrome

Four handlers, all optional, and legal only on a dock_area(...). Each is first called from inside GPUI's layout pass and given base's resolved state. Its description is cached until that state or handler changes.

Motion

The property is one of "opacity", "width", "height", "left", "top", and the frames never enter JavaScript.

Style templates

Each takes a function that receives a detached element to collect styles on; its return value is ignored, so a chain and a block body both work.

Style methods

Everything else on an element is a style. There are two families, and they never overlap:

• Methods that take an argument, bound by hand: the size, padding, margin, position, flex, border, radius and paint families. Which length type each accepts follows its Rust signature, so .p("auto") is a type error for the same reason it throws at run time.
• No-argument methods, generated from GPUI's reflection table: flex_col, items_center, gap_2, rounded_md, text_sm, size_full, truncate and the rest. The generated declarations are the inventory for the GPUI version in your build.

Both are covered in Styling, along with the length and color grammars and the tokens the palette defines.

HostModule registrations

A module the host registered in Rust is imported by name, like any other module:

import { quotes } from "market";

It is not part of any built-in module. The generated declarations carry one declare module per registered module, so both the module name and every export name are checked. See HostModule.

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/shell/api) 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.