gpui-motion-kit

Declarative animation for native Rust apps built with GPUI Kit.

Keep the motion state in your view and describe its next destination. The adapter connects the shared gpui-ce-motion engine to Kit's elements, executor clock, frame scheduling, and reduced-motion preference. No JavaScript or renderer fork.

Crates.io · API reference · Product examples · Text gallery

Install

cargo add gpui-motion-kit@0.2
cargo add gpui-kit@=0.7.3 --features component,assets

Or add these dependencies to your application:

[dependencies]
gpui-motion-kit = "0.2"
gpui-kit = { version = "=0.7.3", features = ["component", "assets"] }

Requires Rust 1.95+ and GPUI Kit's native build prerequisites. This release supports Kit 0.7.3 with its default gpui-pre backend. Use the same Kit version throughout your application; the alternative gpui-fast backend is not supported. macOS is covered by native CI. Linux API documentation builds in CI; Linux/Windows application behavior has not been validated.

You do not need a direct gpui-ce-motion dependency. Portable types such as Motion, Target, and Transition are available through gpui_motion_kit::core. Import native states from gpui_motion_kit, and UI types from gpui_kit. Do not enable the core engine's CE-specific gpui feature for this integration: Kit and CE native types belong to different GPUI crates and cannot be mixed.

Quick start

This complete application animates a panel containing a normal Kit button. Click repeatedly while it moves to interrupt the spring smoothly.

use gpui_kit::{
    AppContext, Context, Render, Window, WindowOptions,
    assets::Assets,
    component::{ActiveTheme, button::Button},
    div, prelude::*,
};

use gpui_motion_kit::{
    MotionState,
    core::{Motion, Target},
};

#[derive(Default)]
struct Panel {
    expanded: bool,
    motion: MotionState,
}

impl Render for Panel {
    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        let width = if self.expanded { 320.0 } else { 180.0 };

        let target = Target::default()
            .width(width)
            .height(96.0)
            .border_radius(16.0);

        let frame = self.motion.frame(Motion::new(target), window, cx);

        let panel = div()
            .p_4()
            .bg(cx.theme().secondary)
            .child(
                Button::new("resize-panel")
                    .label("Resize panel")
                    .on_click(cx.listener(|this, _, _, cx| {
                        this.expanded = !this.expanded;
                        cx.notify();
                    })),
            );

        div()
            .size_full()
            .p_8()
            .bg(cx.theme().background)
            .text_color(cx.theme().foreground)
            .child(frame.apply(panel))
    }
}

fn main() {
    gpui_kit::application().with_assets(Assets).run(|cx| {
        gpui_kit::init(cx);

        gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| {
            cx.new(|_| Panel::default())
        })
        .expect("open animation example");

        cx.activate(true);
    });
}

Motion is a declaration you can recreate each render. MotionState is retained history: keep one state per logical object. Springs preserve position and velocity when interrupted. The adapter requests another frame only while moving; notify the view after an input changes its target. The host app supplies Kit's reduced-motion preference, which the adapter reads when sampling.

The button keeps its Kit behavior. Frame::apply animates its wrapper's relative x/y, opacity, width, height, and border radius. Width and height perform real layout; they are not GPU scale transforms. Applying a corner radius does not clip children automatically. This integration does not automatically animate every internal property of every Kit component.

Enter and exit

Keep declaring the element after open becomes false. Frame::render retains it during the exit and returns an empty element once the exit finishes.

use gpui_kit::{AnyElement, App, Window, div, prelude::*};
use gpui_motion_kit::{MotionState, core::{Motion, Target}};

fn details(state: &mut MotionState, open: bool, window: &mut Window, cx: &App) -> AnyElement {
    let motion = Motion::new(Target::default())
        .initial(Target::default().y(12.0).opacity(0.0))
        .exit(Target::default().y(-8.0).opacity(0.0))
        .present(open);

    let frame = state.frame(motion, window, cx);

    frame.render(|frame| frame.apply(div().p_4().child("Details")))
}

Keep state on the owner. Before removing focused controls, restore focus to a remaining control, and guard outgoing input with frame.is_present().

Text and numbers

Retain TextMotionState and NumberMotionState on your view. These elements use Kit's native text renderer with the same shared text lifecycle and shaping logic as the CE adapter.

use gpui_kit::{IntoElement, SharedString, div, prelude::*};

use gpui_motion_kit::{
    NumberEffect, NumberMotionState, TextMotionState, TextPreset, TextUnit,
    core::StaggerFrom,
};

use std::time::Duration;

fn heading(
    text: &TextMotionState,
    count: &NumberMotionState,
    title: SharedString,
    total: i64,
) -> impl IntoElement {
    let title = text
        .element("heading", title)
        .units(TextUnit::Words)
        .preset(TextPreset::FadeUp)
        .stagger(Duration::from_millis(35), StaggerFrom::Start)
        .when(cfg!(target_os = "macos"), |title| {
            title.font_family("Helvetica Neue")
        });

    let total = count
        .element("total", total)
        .effect(NumberEffect::Roll)
        .when(cfg!(target_os = "macos"), |total| {
            total.font_family("Helvetica Neue")
        });

    div().flex().gap_4().child(title).child(total)
}

The macOS font override avoids a stock system-font clipping issue at display sizes. Text also supports graphemes, wrapped lines, custom targets, matching, reflow, wipes, scrambling, playback and scrubbing. Numbers support Roll, Fade, Slide, and Count. See the text contracts.

Layout positions

Keep one LayoutGroup per coordinate scope and stable IDs for its children. When normal layout moves an item, this wrapper animates from its previous position.

use gpui_kit::{IntoElement, div, prelude::*};
use gpui_motion_kit::LayoutGroup;

fn rows(layout: &LayoutGroup, order: &[usize]) -> impl IntoElement {
    div().flex().flex_col().gap_2().children(order.iter().map(|&id| {
        let row = div()
            .id(("row", id))
            .p_3()
            .child(format!("Task {id}"));

        layout.position(("row-position", id), row)
    }))
}

Paint, hitboxes, and accessibility bounds move together. Sizes change immediately; this is position-only animation, not size projection or cross-parent shared layout.

Animated values

Use ValueState when a Kit control or your own drawing consumes a numeric value. This helper animates a progress fill in logical pixels:

use gpui_kit::{App, IntoElement, Window, div, prelude::*, px, rgb};
use gpui_motion_kit::{ValueState, core::Transition};

fn progress(
    state: &mut ValueState,
    target_width: f64,
    window: &mut Window,
    cx: &App,
) -> impl IntoElement {
    let frame = state.frame(target_width, Transition::default(), window, cx);

    div()
        .w(px(frame.value() as f32))
        .h_2()
        .bg(rgb(0x84cc16))
}

Initialize the retained state once with ValueState::new(0.0). Avoid giving the same property a second interpolator inside a Kit component.

VectorState supplies native compatible-path morphing and stroke reveal; the automation example shows it in a complete flow. Other portable APIs are available through core, but CE-specific native helpers such as GestureState, ScrollMotion, AutoSize, and SharedLayout do not yet have Kit bindings. Drag/drop in the planner uses Kit input plus the shared motion engine. General subtree transforms remain out of scope on the stock renderer.

Product examples

Six interactive product examples are included in the repository and crate archive. Run from the repository root:

cargo run --manifest-path integrations/gpui-kit/Cargo.toml --features demo --example showcase

Use the tabs to switch examples. Each example keeps its state. You can also open one directly by appending -- inbox, -- assets, -- downloads, -- palette, -- kanban, or -- automation.

The inbox supports Command+Backspace to archive and Command+Z to undo on macOS; use Control on other desktop platforms. Command+Q/Control+Q quits. Kit controls keep their native keyboard, focus, and accessibility behavior. Finite transitions honor GPUI's reduced-motion preference. Transfers and releases are explicitly simulated; these examples do not access email, download files, or publish anything. Artwork is embedded in the executable and decoded once at startup. The showcase was validated on macOS; Linux/Windows runs and screen-reader behavior are unverified.

Checks

cargo fmt --manifest-path integrations/gpui-kit/Cargo.toml --all --check
cargo test --manifest-path integrations/gpui-kit/Cargo.toml --locked --features demo,native-tests
cargo test --manifest-path integrations/gpui-kit/Cargo.toml --locked --features demo,native-tests --example showcase
cargo clippy --manifest-path integrations/gpui-kit/Cargo.toml --locked --all-targets --features demo,native-tests -- -D warnings
python3 scripts/check_spacing.py --project integrations/gpui-kit

Append --fix to the spacing command to apply the same shared Dylint policy as the CE crate. The repository's pinned Dylint nightly and CLI are required; see development instructions. The spacing command also compiles every Rust example in this README against Kit. Tests and benchmarks reuse CE fixtures and run from the repository; the published archive contains the library, runnable demos, their assets, and licenses.

Native interaction tests render the production views and dispatch real Kit pointer/keyboard input. TestPlatform substitutes the display/GPU, so those tests verify behavior and geometry rather than GPU presentation.

Performance

cargo bench --manifest-path integrations/gpui-kit/Cargo.toml --features demo,native-tests --bench kit_layout

The benchmark compares direct layout, position tracking without interpolation, and interrupted position animation for 400 elements over seven batches of 240 measured frames, after warmup. It reports CPU construction/layout/prepaint/paint preparation on TestPlatform, not GPU completion or display latency. Keep profile, machine, and workload the same when comparing results. Live-window checks are still needed for presentation, input feel, and platform behavior.

Local release-profile result on macOS ARM64 with Rust 1.95.0, recorded on 2026-10-18 after other builds had finished:

This is one shared-desktop CPU comparison, not a frame-rate guarantee. The animated wrapper adds roughly 0.76 ms to the median batch mean in this workload. These figures do not measure all six product screens or GPU execution.

Text gallery

The native text API shares its renderer and portable engine with the CE adapter. Keep TextMotionState or NumberMotionState from gpui_motion_kit in the owner. Text grouping, targets, presets and number effects are re-exported alongside them; existing transitions, prepared animations and stagger origins come from core.

cargo run --manifest-path integrations/gpui-kit/Cargo.toml --features demo --example text_motion

Try all twelve modes, edit the input, or press Change text repeatedly while it moves. Replay/Pause/Resume control text playback; Scrub exposes a draggable reveal slider. Numbers demonstrates Roll/Fade/Slide/Count with increment/decrement buttons. The reduced-motion checkbox settles every mode. The text API and contracts cover Unicode shaping, matching, clipping, playback and the finite scrub horizon.

The text-native benchmark compares ordinary text replacement, settled adapter rendering, interrupted word/grapheme movement and deterministic scrambling for 40 labels. Like the layout benchmark, it measures CPU preparation on TestPlatform.

The final local run measured 0.271 ms/frame for ordinary text, 0.419 ms for interrupted words, 0.542 ms for graphemes and 0.560 ms for scrambling. These are median batch means; see measurement details and P95 for workload differences, repeat-run variation and the stock-CE comparison.

MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.