tiamat

name	tiamat
description	Learn how to use Tiamat — a Compose Multiplatform navigation library. Covers destination basics, arguments and results, advanced navigation actions, generated graphs, ViewModel and retained state, custom layouts and transitions, and extensions.
metadata	{"author":"ComposeGears","keywords":["recipe","Kotlin Multiplatform","Compose Multiplatform","Tiamat","navigation","navDestination","NavController","Navigation","NavigationScene","ViewModel","retain","TiamatGraph","extensions","transitions","adaptive layout"]}

Developer documentation

• Tiamat overview: Overview of the Tiamat navigation library — core concepts, API surface, and how to get started.

Recipes

Code examples showcasing common patterns.

Destination basics

• Simple screen: Create a screen with navDestination and wire it into a Navigation host.
• Navigate between screens: Perform forward and back navigation between destinations.
• Preview destinations: Render any destination inside a Compose @Preview with TiamatPreview.
• Global transition style: Override the default animation for an entire Navigation host.

Arguments and results

• Typed arguments: Declare a destination with required or optional typed args.
• Free args: Pass lightweight transient data with freeArgs.
• Serializable args: Use NavData + @Serializable for args that survive process death.
• Back results: Pass typed results back to the previous destination.

Common UI

• Tab navigation: Tab navigation where each tab has its own independent back stack.

Advanced navigation actions

• Replace and pop-to-top: Use replace, back(to=…), and popToTop for tab-style and flow navigation.
• Per-call transitions: Override animations for a single navigation call.
• Route API: Build a multi-step back stack in one call or navigate by destination name.
• Edit nav stack: Arbitrary stack manipulation with editNavStack.
• Observe NavController state: Drive UI from reactive NavController state.
• NavController configuration: Apply a configuration callback at NavController creation time.
• Nested NavControllers: Navigate across nested NavController hierarchies.

Generated graph

• Graph setup and usage: Configure TiamatGraph, @InstallIn, install in multiple graphs, and merge graphs.

ViewModel and state

• Screen-scoped ViewModel: Scope a ViewModel to a single screen.
• Shared ViewModel: Share a ViewModel across all destinations under a NavController.
• Retain: Retain objects across backward navigation with retain {}.
• Produce retained state: Coroutine-driven retained state with produceRetainedState.
• SavedStateHandle ViewModel: ViewModel with SavedStateHandle for process-death survival.
• Custom save and restore state: Manually save and restore a NavController's state with saveToSavedState().

Architecture

• Koin ViewModel: Use Koin's koinViewModel with Tiamat for dependency-injected ViewModels.
• Hilt ViewModel: Use Hilt's hiltViewModel with Tiamat for dependency-injected ViewModels on Android.

Custom layouts and transitions

• NavigationScene basics: Full layout control with NavigationScene.
• Overlay destinations: Dialogs and bottom sheets rendered in the nav stack.
• Two-pane layout: List-detail / two-pane adaptive layout.
• Adaptive list-detail: Responsive layout that switches between single-pane and two-pane based on window size.
• Gesture transitions: Gesture-driven / seekable transitions with TransitionController.
• Shared-element transitions: Shared-element transitions with LocalNavAnimatedVisibilityScope.

Deep links

• Deep link: Parse deep-link URIs into routes using pattern-based matching with DeepLink.

Extensions

• Marker extensions: Attach metadata to destinations with NavExtension.
• Content extensions: Inject composable UI overlays/underlays with ContentExtension.