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.
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.
- 01Add it to your appPick a toolchain, add the package, paste the counter, swift run.
- 02Authoring ViewsCompose containers, local state, focused controls, and modifiers around a body-driven tree.
- 03State, Environment, and FocusState, observation, environment, and focus share one runtime invalidation path.
- 04Running AppsThe @main entry point, the standard flags, exit keys, and rendering one frame without a TTY.
- 05Coming from SwiftUIWhat transfers unchanged, which reflexes need retraining, and what is not here yet.
Build your interface
Views, controls, drawing, and animated images. Read the guides as you need them.
Forms and ControlsCompose buttons, pickers, toggles, sliders, and text entry into a working form.Commands and Key InputFocus-scoped arrows and Escape, keyboard shortcuts, submit actions, and command palettes.ScrollingFinite viewports, compositional lazy stacks, nested wheel routing, indicators, and scrolling from code.Animating ViewsState animation, default fades, numeric text, nested matched geometry, keyframes, and reduced motion.Navigation and TabsTyped navigation paths, destinations, tab selection, and view lifetime.Animated Images and GIFsDecode and author frames, control finite or continuous playback, and preserve GIF loop metadata on export.The Style SystemAll 28 open style families in one place: built-ins, scoping, custom conformances, routes, theming, diagnostics, and tests.Styling and ThemingColors, semantic roles, gradients, the theme model, and your first custom button style.Authoring StylesThe contract every style family shares: body-producing and presentation-value styles, route wrappers, and what a style may change.Testing StylesExercise custom styles with fixture configurations, snapshots, and runtime route checks.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.ShapesArcs and angles, fills and strokes, shape clipping, and compatible-topology path animation.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.
At run time
What a running terminal app reads and can do, from the SwiftTUIRuntime catalog.
Performance for App AuthorsStable identity, certified memo reuse, lazy content, and a measurement-led profiling workflow.Logging and DiagnosticsSafe logging while the app owns the screen, runtime issues, traces, and debug bundles.Testing Your AppRender deterministic frames without a TTY and test state, layout, and interaction.Distributing Your AppPackage a native executable, standard flags, shell completions, and platform requirements.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 with SwiftTUITerminalView from the separate terminal-view package.
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.
Adapting an Interface to Its HostOne shared tree with touch targets, keyboard access, navigation, and scrolling suited to its host.Deploying to the BrowserServe a local app with --web or publish a static WASI bundle with the browser host packages.Embedding in SwiftUINative macOS and iOS hosting, touch panning, text input, and optional keyboard controls.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
What You Can BuildDrawing, animation, scrolling workspaces, and interaction, with examples and links into the guides.Public Module MapGenerated product ownership, supported direct imports, and transitive re-exports from source.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
- SwiftTUI — the batteries-included app product
- SwiftTUIViews — views, controls, layout, state, focus
- SwiftTUIRuntime — scenes, run loop, host integration
- SwiftTUICharts — charts and compact metrics
- SwiftTUITerminalView — embedded terminal program panes
Hosts and opt-in products
- SwiftTUICLI — terminal-only runner
- SwiftTUIWebHostCLI — terminal runner with --web
- SwiftTUIArguments — SwiftTUIOptions and command parsing
- SwiftTUIWebHost — localhost browser host
- SwiftTUIWASI — WASI and browser builds
- SwiftTUIAndroidHost — Android embedding
- SwiftTUIAnimatedImage — animated GIF and image views
- SwiftTUIProfiling — opt-in profiling and diagnostics
- SwiftUIHost — native SwiftUI embedding (separate package)
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.