SwiftTUI Examples

SwiftUI semantics, drawn in terminal cells, and the same authored App shipped to every host. This repo holds runnable examples for SwiftTUI: one directory per demo, each proving a specific capability, each with the exact command to run it.

Start here

Pick by what you want to see, then run one command:

• The most in one window: run gallery for tabs, controls, charts, images, animated GIFs, popovers, and physics in a single terminal app.
• One source on every host: clone swift-tui-counter-demo to run the same shared CounterView in a terminal, an embedded native SwiftUI window, the browser as a static WASI bundle, and an Android app — each host declares its own App over that one view (the browser build also powers the live demo on swifttui.sh).
• The smallest possible start: read minimal, one RenderOnce.print(...) with no app runtime and no argument parser.
• A polished document reader: run mrkdwn for complete GFM compilation, responsive navigation, XDG theming, and bounded images.
• A terminal data workbench: run csvui for lazy CSV/TSV viewing, sparse editing, projections, live reload, and conflict-aware atomic saves.

Building something specific? Scan the roster by what each example proves, or jump straight to a package in By product.

Prerequisites

• Swift 6.4.x (.swift-version pins 6.4.0).
• Commands below use swiftly so every example builds against the repository pinned toolchain. If Swift 6.4.x is active through Xcode 27 or PATH, remove the swiftly run prefix. Then run the bare swift ... command.
• Xcode 27 or newer for the SwiftUIExample Xcode project. Its package resolver must support Swift tools 6.4. The repository gate selects the Swiftly-managed compiler explicitly for this build.

Run from the repo root unless a local README says otherwise.

Quick start

git clone https://github.com/SwiftTUI/swift-tui-examples.git
cd swift-tui-examples
swiftly run swift run --package-path gallery gallery-demo   # the full workbench
swiftly run swift run --package-path minimal minimal        # the smallest path

Each example builds from a fresh clone with tagged HTTPS dependencies. Each example pins the current 0.13.5 release graph. Gallery uses matching swift-tui and swift-tui-charts versions. mrkdwn uses the independent swift-markdown release range. No sibling source checkout is necessary.

Roster

Example	Host	What it proves	Run
minimal	CLI	Smallest RenderOnce.print(...) path for report-like CLI output, with no app runtime or argument parser	swiftly run swift run --package-path minimal minimal
hot-reload	Terminal	Codable integer/reference counter with a guarded compiled-reload export and lifecycle probe; current tag supports normal execution	swiftly run swift run --package-path hot-reload HotReloadDemo
equatable-demo	Terminal	Smallest View.equatable() usage: a stable panel is memoized (reused across frames) while a counter updates	swiftly run swift run --package-path equatable-demo EquatableDemo
argparse	Terminal	SwiftTUI.App command conformance, consumer flags, standard SwiftTUI flags, and completions in one app type	swiftly run swift run --package-path argparse argparse-demo --help
gallery	Terminal+Web	Primary component workbench: tabs, controls, the style system (all 28 open style families, built-ins beside custom conformances), palette, text input, scroll commands, charts, images, animated GIFs, file drop, popovers, and logo-breaker physics	swiftly run swift run --package-path gallery gallery-demo
layouts	Terminal	SwiftTUI layout catalog with behavior tests for stacks, frames, geometry, scrolling, overlays, shapes, matched geometry, and custom layouts	swiftly run swift run --package-path layouts layouts-demo
LayoutsSwiftUI	Native SwiftUI	Native SwiftUI layout catalog beside the embedded SwiftTUI catalog through SwiftUIHost	swiftly run swift run --package-path LayoutsSwiftUI layouts-swiftui-demo
AndroidGallery	Android	Compose host app embedding the SwiftTUI gallery through SwiftTUIAndroidHost and the Swift Android SDK	(cd AndroidGallery && ./gradlew :app:assembleDebug)
sextant	Terminal	Miller-column browser and file previews through SwiftTUITerminalView / TerminalProcessSession	swiftly run swift run --package-path sextant sextant
terminal-workspace	Terminal	Terminal multiplexer built on SwiftTUITerminalView, with an example-owned workspace layer: tabs, splits, retained sessions, command-palette actions, and persisted layout metadata	swiftly run swift run --package-path terminal-workspace terminal-workspace
mrkdwn	Terminal	Responsive CommonMark/GFM reader with outline, search, local-document history, XDG TOML themes, and bounded images	swiftly run swift run --package-path mrkdwn mrkdwn README.md
csvui	Terminal	Viewer-first CSV/TSV workbench with lazy row decoding, sparse edits, search/filter/sort projections, XDG theming, live reload, and safe atomic saves	swiftly run swift run --package-path csvui csvui data.csv
git-viz	CLI	SwiftTUICharts over real git data, with a command for every chart primitive	swiftly run swift run --package-path git-viz git-viz dashboard --path .
gifcat	Terminal	SwiftTUIAnimatedImage playback, source GIF delays, regular-size image attachments, and row-major tiling of multiple GIFs	swiftly run swift run --package-path gifcat gifcat gifeditor/nyan.gif
gifeditor	Terminal+Web	Full GIF editor: half-cell canvas, palette, tools, layers, timeline, pointer input, undo/redo, and GIF import/export	swiftly run swift run --package-path gifeditor gifeditor
SwiftUIExample	Native SwiftUI	SwiftUI host app embedding reusable SwiftTUI scenes through SwiftUIHost	open SwiftUIExample/SwiftUIExample.xcodeproj
swift-tui-counter-demo	Multi-host	Own repo: one shared CounterView runs in the terminal, embeds in a native SwiftUI window via SwiftUIHost, ships as a static WASI browser bundle (the swifttui.sh live demo), and runs on Android	git clone https://github.com/SwiftTUI/swift-tui-counter-demo.git
WebHostExample	Terminal+Web	Smallest SwiftTUI convenience app: terminal by default, localhost browser host with --web	swiftly run swift run --package-path WebHostExample WebHostExample --web

By product

Already know the package you need? Jump straight to an example that uses it.

Product or package	Examples
SwiftTUI convenience surface	argparse, gallery, layouts, sextant, terminal-workspace, mrkdwn, csvui, gifcat, gifeditor, WebHostExample
SwiftTUIRuntime / host-managed scenes	gallery, swift-tui-counter-demo
SwiftTUICLI / one-shot rendering and terminal launch	minimal, git-viz
SwiftTUIArguments / SwiftTUICommand	argparse, gallery, gifeditor, git-viz
SwiftTUICharts (separate swift-tui-charts package)	git-viz, gallery, layouts
SwiftTUIAnimatedImage	Included by SwiftTUI. Used directly by gifcat and gallery
SwiftTUITerminalView	sextant, terminal-workspace
SwiftUIHost	SwiftUIExample, swift-tui-counter-demo
SwiftTUIAndroidHost	AndroidGallery
SwiftTUIWebHostCLI	Included by SwiftTUI. Used directly by gifeditor
SwiftTUIWASI, @swifttui/web, @swifttui/build	swift-tui-counter-demo (own repo, the swifttui.sh live demo)

The coverage document contains the full matrix, category definitions, gate contract, and new-example checklist. For the APIs behind these demos, read the DocC reference, and see the showcase for these examples running on every host. The host halves live in the sibling repositories swift-tui-swiftui (native SwiftUI host), swift-tui-web (browser packages), and swift-tui-android (Android host).

Tests

CI runs three lanes (.github/workflows/):

• Framework seam (bun run check:linux, every push and pull request): builds every package in debug and runs the suites that exercise SwiftTUI behaviour — WebHostExample, mrkdwn's view/model/journey suites, csvui's view-contract and journey suites, gallery, gifcat. Every step runs under a silence watchdog (Scripts/lib/step_watchdog.sh), so a hang is killed with a thread dump after minutes instead of running to the job cap.
• App logic (bun run check:focused, or --package <name> for one): gifeditor, sextant, git-viz, terminal-workspace, and the mrkdwn/csvui domain suites. These test the apps rather than the framework, so they run when their package changes, on dispatch, and on release tags.
• Framework HEAD seam (.github/workflows/framework-head.yml, every six hours, skipped when nothing landed): the framework-seam lane against the main branches of swift-tui and swift-tui-charts. Scripts/localize_siblings.sh clones the siblings, copies this repository into a throwaway directory, rewrites the copy's manifests to local paths, and runs the gate there; the committed manifests keep their tags.

To test one example, run swiftly run swift test --package-path <example>. Release-configuration builds (bun run check:release) run on tags and explicit release-build dispatches. The macOS lane also runs on main pushes. To validate the complete release build before tagging:

gh workflow run test.yml --ref <candidate-branch> -f run_macos=true -f release_builds=true

The gate groups debug builds before release builds so Swift Build can reuse the shared framework's optimized products across examples. See the coverage document for the check:linux, check:macos, and check build gates and their scratch-directory environment variables, and AGENTS.md for the toolchain policy.

License

MIT. See LICENSE.