From ea950dbbb95361a2e6313d8efe45a0ce2556511b Mon Sep 17 00:00:00 2001
From: sunwukk990 <82385875+grgwuk990@users.noreply.github.com>
Date: Wed, 29 Apr 2026 08:36:29 -0400
Subject: [PATCH] gpui: Add examples index (#55154)

Self-Review Checklist:

- [x] I've reviewed my own diff for quality, security, and reliability
- [x] Unsafe blocks (if any) have justifying comments
- [x] The content is consistent with the [UI/UX
checklist](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)
- [x] Tests cover the new/changed behavior
- [x] Performance impact has been considered and is acceptable

Closes #ISSUE

Release Notes:

- N/A

---------

Co-authored-by: Christopher Biscardi <chris@christopherbiscardi.com>
---
 crates/gpui/README.md          |  2 +-
 crates/gpui/examples/README.md | 71 ++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+), 1 deletion(-)
 create mode 100644 crates/gpui/examples/README.md

diff --git a/crates/gpui/README.md b/crates/gpui/README.md
index ad3fd37fc5..e7950de23a 100644
--- a/crates/gpui/README.md
+++ b/crates/gpui/README.md
@@ -11,7 +11,7 @@ GPUI is still in active development as we work on the Zed code editor, and is st
 gpui = { version = "*" }
 ```
 
- - [Ownership and data flow](_ownership_and_data_flow)
+- [Ownership and data flow](_ownership_and_data_flow)
 
 Everything in GPUI starts with an `Application`. You can create one with `Application::new()`, and kick off your application by passing a callback to `Application::run()`. Inside this callback, you can create a new window with `App::open_window()`, and register your first root view. See [gpui.rs](https://www.gpui.rs/) for a complete example.
 
diff --git a/crates/gpui/examples/README.md b/crates/gpui/examples/README.md
new file mode 100644
index 0000000000..7fc75e0f5b
--- /dev/null
+++ b/crates/gpui/examples/README.md
@@ -0,0 +1,71 @@
+# GPUI Examples
+
+Examples can be run from the Zed repository root:
+
+```sh
+cargo run -p gpui --example hello_world
+```
+
+## Where to start
+
+- `hello_world` shows the basic shape of a GPUI application: create an
+  `Application`, open a window, create a root view, and render a `div`.
+- `input` demonstrates text input, focus, selections, clipboard actions, and
+  keyboard bindings.
+- `uniform_list` shows how to render a simple virtualized list.
+- `testing` demonstrates `#[gpui::test]`, `TestAppContext`, actions, focus, and
+  window-based tests.
+
+## Layout and styling
+
+- `grid_layout` demonstrates CSS-grid-style layout.
+- `opacity` demonstrates opacity styling.
+- `pattern` shows patterned backgrounds.
+- `shadow` demonstrates box shadows.
+- `text` shows styled text rendering.
+- `text_layout` demonstrates text alignment, decoration, weights, and wrapping.
+- `text_wrapper` shows wrapping text content.
+
+## Interaction
+
+- `anchor` demonstrates anchored positioning.
+- `data_table` combines virtualized list rendering with table-style rows and a
+  custom scrollbar.
+- `drag_drop` shows draggable elements and drop targets.
+- `focus_visible` demonstrates keyboard-visible focus styling.
+- `mouse_pressure` demonstrates pressure-sensitive pointer input where supported.
+- `popover` shows floating layers with `deferred` and `anchored`.
+- `scrollable` demonstrates scrollable content.
+- `tab_stop` shows keyboard tab navigation.
+
+## Images, drawing, and animation
+
+- `animation` demonstrates GPUI animations and animated SVG transforms.
+- `gif_viewer` shows GIF rendering.
+- `gradient` demonstrates linear gradients and color spaces.
+- `image` shows local and remote image loading, image sizing, and asset setup.
+- `image_gallery` demonstrates image caching and loading remote images.
+- `image_loading` shows image loading states and asset loading.
+- `painting` demonstrates custom drawing with paths and canvas.
+- `svg` shows SVG rendering.
+
+## Windows and application behavior
+
+- `move_entity_between_windows` shows moving an entity between windows.
+- `on_window_close_quit` demonstrates quitting when a window closes.
+- `set_menus` shows application menu setup.
+- `window` demonstrates creating normal, dialog, popup, and floating windows.
+- `window_positioning` demonstrates window bounds and placement.
+- `window_shadow` demonstrates window shadow styling.
+
+## Specialized examples
+
+These examples are useful when working on GPUI itself, but they may not be the
+best starting point for new applications:
+
+- `active_state_bug` is a focused active-state reproduction.
+- `layer_shell` demonstrates Linux layer-shell windows.
+- `list_example` demonstrates bottom-aligned list state and scrollbar behavior.
+- `ownership_post` supports the ownership and data-flow documentation.
+- `paths_bench` is a path rendering benchmark.
+- `tree` renders a deep tree of nested elements.