Skip to content
chrx3Public

About

Material 3 Expressive components for GPUI: shape morphing, spring motion and dynamic color

Topics

Resources

Stars

11 stars

Watchers

0 watching

Forks

Repository files navigation

gpui-m3

Material 3 Expressive components for GPUI, the GPU-accelerated UI framework behind the Zed editor.

Shape morphing, physical spring motion, ripples, dynamic color and the M3 Expressive shape library — built natively for GPUI, no web view involved.

Gallery, dark theme

Selection controls Shapes
Menus Progress
Text fields and feedback

Try it

git clone https://github.com/chrx3/gpui-m3
cd gpui-m3
cargo run --example gallery

For a whole app built from the library, cargo run --example showcase_music opens a Material 3 Expressive music player (SHOWCASE_DEMO=1 runs a scripted tour of it).

The gallery shows every component with light/dark mode, nine seed colors and a Slow ×5 switch to inspect the motion, and a What's new section with the notes of every version. The first build compiles GPUI and takes a few minutes. M3_SECTION=<n> opens a section directly, M3_SIZE=<width>x<height> sets the window size and M3_MODE=light|dark and M3_SEED=<n> the look (handy for screenshots). How release notes are written: changelog/README.md.

Install

[dependencies]
gpui = "0.2.2"
gpui-m3 = "0.2"
use gpui::*;
use gpui_m3::{Button, Switch, Theme};

fn main() {
    Application::new().with_assets(gpui_m3::Assets).run(|cx: &mut App| {
        gpui_m3::init(cx); // font, key bindings, light baseline theme
        Theme::set(true, Some(gpui_m3::theme::hex("#0b57d0")), cx); // dark, dynamic color
        // open your window...
    });
}

// In a render method:
div()
    .font_family(gpui_m3::theme::FONT_FAMILY)
    .child(Button::new("save", "Save").filled().on_click(|_, _, _| {}))
    .child(Switch::new("wifi", self.wifi).on_toggle(/* ... */))

Components are RenderOnce and keep their animation state between frames, so each one needs an id that is unique within its view, like any stateful GPUI element. TextField is the exception: it is an entity you create once (cx.new(|cx| TextField::new(cx))) and keep in your view.

Components

Group Components
Buttons Button (filled, tonal, outlined, text, ghost; 6 sizes; toggle, sublabel, confirmation, busy), IconButton (tooltip, launch, icon swap), Fab (busy, disabled, colors), FavStar, ButtonGroup (standard and connected)
Selection Switch (thumb icons), SegmentedButtons (multi-select, dense), StopSlider (also vertical), Slider (continuous, centered, vertical, five Expressive sizes with icon, ticks, value indicator), RangeSlider, Chip (assist, filled, filter, input, tonal, small, danger), SplitButton (filled, tonal, outlined, with its menu), Badge, Radio (error), Checkbox (indeterminate, error), ChoiceRow (indeterminate, error), MorphDot
Navigation NavItem (drawer rows), RailItem, IconTabs, TabStrip, TreeRow, ListItem (selected, overline, supporting text, hover actions), TopAppBar (small, centered, medium and large, collapsing), Toolbar (floating and docked, dense, custom items), PageIndicator, Carousel (multi-browse, uncontained, hero, center hero, full-screen; drag, wheel, keys, snap), FabMenu
Text & feedback TextField (pill, compact, inline, bare, filled, outlined; error and supporting text, character counter, prefix and suffix, disabled, read-only), TextArea (multi-line; error, supporting text, counter), DatePicker (docked or modal; day or range; DateNames), TimePicker (dial or number fields; 12 h or 24 h), CommandPalette, SuggestionList (@-mentions, with SuggestionNav, match_ranges, rank_mentions), Dialog, Toast, Tooltip, context_menu, Banner, EmptyState, ShimmerText, DividerLabel, SearchBar and SearchView, RichTooltip
Surfaces Menu (header, back row, scrolling, grows from its anchor), MenuItem (dense, radio, danger, shortcuts), Popover, reveal (a surface that grows out of its anchor), Card, ExpandableCard (tonal, error), ListGroup, Bubble, BottomSheet, SideSheet, Divider
Shapes & progress Shape (14 shapes, breathe, breathe on hover, photo fill, spin), Avatar (initials or a photo), LoadingIndicator, WavyProgress and WavyCircularProgress (also still), Ring (warning threshold), LinearProgress, StatusMark (pending, running, done, failed, waiting)
Attachments DropZone (files from the system), ImageThumb
Code CodeEditor over a CodeBuffer (virtualized with uniform_list, line numbers, mouse and keyboard selection, clipboard, undo/redo, read-only mode, a LineHighlighter hook), Markdown (GFM: tables, tasks, nested lists, quotes, links, paths; parsed with pulldown-cmark and cached), CodeBlock (language name, Copy → Copied, highlighting), CodeOutput (clipped tool output, by lines or characters, JSON pretty printing), JsonView (foldable JSON, json feature), DiffView / Diff (real line diff with similar, folding, +N −M), DiffBar
Appearance SelectCard, ColorSwatches, HsvPicker
Settings & keys SettingRow (title, description and a control on the right, for a ListGroup), Kbd (one key cap), KeyCombo (a combination such as ctrl-shift-k in a row, clickable, with a pulsing "capturing" state), KeyNames (English or Spanish key words), parse_keys
Foundations theme (Scheme with its nine SchemeVariants and contrast levels, Theme, Elevation, corner), syntax (SyntaxHighlighter line by line, SyntaxPalette), motion (Spring, animate*, entrance, Enter with shared axis, presence, play_on_rise), Presence (exit animations), shapes, interaction (state layer, ripples, focus ring)

Theming

  • Theme::set(dark, None, cx) uses the M3 baseline (purple) scheme.
  • Theme::set(dark, Some(seed), cx) generates a scheme from any color (tonal spot, via material-colors).
  • Theme::set_scheme(scheme, dark, cx) uses your own colors — handy when your app already has design tokens. See docs/INTEGRATING.md.

Syntax colors

CodeBlock and SyntaxHighlighter reduce tokens to a few kinds (keyword, string, function, type, comment, number, meta) painted with a SyntaxPalette derived from the scheme: keywords in primary, strings in success, types in tertiary, comments in outline, numbers in warning. SyntaxPalette::set(Some(palette), cx) uses your own colors.

Highlighting uses syntect with its bundled Sublime Text syntaxes and the pure-Rust regex engine (no C toolchain), plus compact grammars for TypeScript, TOML and PowerShell. It works line by line with a cloneable state, so an editor can re-highlight from the edited line.

Motion

M3 Expressive motion is spring-based. GPUI's with_animation only accepts easing curves that stay within 0–1, so gpui-m3 solves damped springs analytically, using the official MotionScheme.expressive() values from Jetpack Compose:

Spring Stiffness Damping Used for
SPATIAL_FAST / SPATIAL / SPATIAL_SLOW 800 / 380 / 200 0.6 / 0.8 / 0.8 position, size, shape (bouncy)
EFFECTS_FAST / EFFECTS / EFFECTS_SLOW 3800 / 1600 / 800 1.0 color, opacity (no bounce)

Retargeting mid-flight keeps the current velocity, so rapid clicks feel continuous. Use the same helpers in your own components:

let radius = gpui_m3::motion::animate_px("card-radius", Spring::SPATIAL_FAST, target, window, cx);

MotionSettings { reduced: true, .. } turns all motion off; time_scale slows it down for review.

Performance

  • Build GPUI optimized. Unoptimized GPUI is 3–5× slower. Copy the [profile.dev] sections from this crate's Cargo.toml into your app (dependencies at opt-level = 3).
  • Continuous animations re-render their view and every ancestor view each frame. Keep loading indicators and breathing shapes in small views, and wrap large static siblings in cached views (AnyView::from(entity).cached(style)), as the gallery does.
  • Every animated shape, wave or ring is a path that GPUI rasterizes each frame (~4% of a core on an integrated GPU). Avoid many at once. Slow ambient motion runs at 30 fps (motion::continuous_at).

With nothing animating, the gallery does not redraw at all.

Differences from the web version of M3 Expressive

  • GPUI cannot scale arbitrary elements, so press "shrink" effects resize the component instead, and menus enter by rising and fading without the scale(0.9).
  • GPUI clips only to rectangles; ripples are drawn as the intersection of a circle and the component's rounded rectangle.
  • material-colors 0.4 implements the 2021 dynamic color spec (0.5 requires Rust 1.97).
  • Roboto ships as a variable font with weights; width axes (font-stretch) are not available in GPUI.
  • Monospace text uses the platform font (Consolas, Menlo or DejaVu Sans Mono); none is bundled.
  • GPUI does not select text, so Markdown offers no selection; put a Copy action next to it. CodeEditor does its own selection: use it with .read_only(true) for text people need to copy.
  • GPUI 0.2.2 caches text measurements without the truncation width, so text with text_ellipsis() can stay as "…" if its first layout was very narrow. Button and SelectCard clip instead.

Roadmap

  • SuggestionList: animate rows that appear while typing by identity, not by position.
  • Focus rings on the other clickable components (buttons, menu items, rows).
  • CodeEditor (already usable): code folding and multiple cursors.
  • Syntax colors inside DiffView lines, and a side-by-side diff.
  • Markdown: selectable text, hover underline on links, footnotes and math.

Status

0.1 is young. It is developed and tested on Windows; it also builds on Linux (checked in a Debian container) and built on macOS in earlier CI runs, but neither is used day to day. GPUI itself is pre-1.0 and changes its API between versions, so gpui-m3 tracks gpui 0.2.x.

On Linux, gpui 0.2.2 pulls in xattr 0.2.3, which does not compile with libc 0.2.190 or later. gpui-m3 therefore requires libc below 0.2.190 on Linux; if another dependency of yours needs a newer one, the two cannot be resolved together until GPUI updates.

Credits

  • Text editing in TextField is based on GPUI's examples/input.rs (Apache-2.0).
  • Motion values from Jetpack Compose Material 3 (Apache-2.0).
  • Syntax highlighting by syntect (MIT) and its bundled Sublime Text syntaxes; Markdown parsing by pulldown-cmark (MIT); diffs by similar (Apache-2.0).
  • Some icons are based on Lucide (ISC) and Feather (MIT); see assets/icons/LICENSE-LUCIDE.txt.
  • Roboto by The Roboto Project Authors, under the SIL Open Font License 1.1.
  • Inter by The Inter Project Authors (Rasmus Andersson), under the SIL Open Font License 1.1. It is the default family; Roboto stays available through theme::set_font_family.
  • "Material Design" is a trademark of Google. This project is not affiliated with or endorsed by Google.

License

Code licensed under either of MIT or Apache-2.0, at your option. The bundled Roboto font is licensed under the OFL 1.1; icons derived from Lucide and Feather keep their notices in assets/icons/LICENSE-LUCIDE.txt.

About

Material 3 Expressive components for GPUI: shape morphing, spring motion and dynamic color

Topics

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages