SwiftTUI

Documentation

SwiftTUI documentation

Organized by what you're doing: your first hour, then the reference guides for views, state, and focus, charts, and what lies beyond the terminal. The module-by-module API reference is at the end.

Get startedOpen the API reference

Your first hour

Read these in order. Each one picks up where the last left off, from an empty package to an app that handles state, focus, and the terminal's own rules.

  1. 01Add it to your appPick a toolchain, add the package, paste the counter, swift run.
  2. 02Authoring ViewsCompose containers, local state, focused controls, and modifiers around a body-driven tree.
  3. 03State, Environment, and FocusState, observation, environment, and focus share one runtime invalidation path.
  4. 04Running AppsThe @main entry point, the standard flags, exit keys, and rendering one frame without a TTY.
  5. 05Coming from SwiftUIWhat transfers unchanged, which reflexes need retraining, and what is not here yet.

Build your interface

The reference guides, one per subsystem, from the SwiftTUIViews catalog. Read them as you need them.

Understanding FocusThe runtime focus model for input routing, state control, and context export.Lists and TablesCollections with authored row content, selection, and viewport-backed data sources.Geometry and PreferencesAnchor preferences let a subtree publish geometry that other views resolve after layout.ShapesFill, stroke, and inset built-in and custom Path shapes, rasterized to Braille subpixels.Aspect-correct shapesCell pixel metrics keep circles circular across terminal fonts and hosts.Pointer and CanvasOne continuous cell coordinate space for gestures, hover, and drawing.AccessibilitySemantic metadata for terminal screen readers, browser ARIA trees, VoiceOver, and TalkBack.Custom Dynamic PropertiesBuild your own property wrappers on the DynamicProperty extension point.State KeyingHow @State storage is keyed across evaluations, and where owners survive lazy seams.Dormant Tab StateWhat happens to a tab's persistent state while the tab is not selected.Dismissal Is DataPresentations are driven by Boolean bindings and identifiable items, not hidden stacks.

Charts

Sparklines, bar and line charts, heatmaps, meters, and calendar views ship separately as swift-tui-charts, composed on the same view surface.

Building DashboardsThe charts guide: layout, scales, live data, and thresholds.SwiftTUICharts referenceEvery chart view and support type, in its own DocC archive.Charts in the showcaseEvery charting primitive exercised against a real repository.

At run time

What a running terminal app reads and can do, from the SwiftTUIRuntime catalog.

Environment VariablesEvery SWIFTTUI_* environment variable the framework reads, grouped by subsystem.Terminal HandoffsTemporarily hand the interactive terminal back to the user's shell mid-run.Terminal EmbeddingHost external terminal programs inside SwiftTUI layout with SwiftTUITerminal.

Beyond the terminal

Terminal first, not terminal only. The same app runs in a browser, inside native SwiftUI windows, and on Android; these guides own that path and its platform notes.

Hosts and PlatformsThe browser (--web and static WASI bundles), native SwiftUI windows, and Android, with the support matrix.Runner and Host IntegrationHow apps launch through runner products or live inside host products.Choosing Modules and PlatformsOne dependency and one import for most apps, plus the product matrix when you need a narrower build.

Concepts and background

Differences from SwiftUIThe primer: what transfers, and the deliberate terminal-native rereadings.Under the hoodAn interactive walkthrough of the frame pipeline, from body to terminal cells.Runtime Render PipelineThe developer-level reference for the same pipeline: phases, products, and commit policy.About SwiftTUIWhy the framework exists and what it optimizes for.Divergences and gapsThe public register of API departures from SwiftUI and known gaps at HEAD.

API reference by module

The combined DocC archive documents each module. Most app code touches only the first row.

What you import

Hosts and opt-in products

The last group declares types that reach app code through re-export — CellSize, Alignment,PreferenceKey, SwiftTUIOptions — so their pages document symbols you use, behind imports you never write.