Overview
A KSP library that processes annotations and generates code that uses Official Jetpack Compose Navigation under the hood. It hides the complex, non-type-safe and boilerplate code you would have to write otherwise.
No need to learn a whole new framework to navigate - most APIs are either the same as with the Jetpack Components or inspired by them.
Main featuresβ
- Typesafe navigation arguments
- Simple but configurable navigation graphs setup
- Navigating back with a result in a simple and type-safe way
- Getting the navigation arguments from the
SavedStateHandle
(useful in ViewModels) andNavBackStackEntry
in a type-safe way - Navigation animations through integration with Accompanist Navigation-Animation
- Bottom sheet screens through integration with Accompanist Navigation-Material
- Easy deep linking to screens
- All you can do with Official Jetpack Compose Navigation but in a simpler safer way!
Materialsβ
- Alex Styl's quick introduction videos Navigate using the Compose Destinations library
- Philipp Lackner's Youtube video Compose Navigation Just Got SO MUCH EASIER π±
- Rafael Costa's blog post Compose Destinations: simpler and safer navigation in Compose with no compromises
- Yanneck ReiΓ's blog post Type Safe Navigation With Jetpack Compose Destinations
- Google Dev Expert Kenji Abe's blog post Navigation ComposeγδΎΏε©γ«γγ¦γγγγ©γ€γγ©γͺ
- aseem wangoo's blog post (and Youtube video inside): Using compose destinations
Communityβ
Please join the community at Kotlin slack channel: #compose-destinations
Ask questions, suggest improvements, or anything else related to the library.
Basic Usageβ
1. Annotate your screen Composables with @Destination
β
@Destination
@Composable
fun ProfileScreen() { /*...*/ }
2. Add navigation arguments to the function declarationβ
Parcelable
, Serializable
, Enum
types and classes annotated with @kotlinx.serialization.Serializable
(as well as Array
s and ArrayList
s of these) are allowed with no additional setup!
Besides, you can make any type a navigation argument type with a one-time simple setup.
@Destination
@Composable
fun ProfileScreen(
id: Int, // <-- required navigation argument
groupName: String?, // <-- optional navigation argument
isOwnUser: Boolean = false // <-- optional navigation argument
) { /*...*/ }
There is an alternative way to define the destination arguments in case you don't need to use them inside the Composable (as is likely the case when using ViewModel). Read more here.
3. Build the projectβ
Or ./gradlew kspDebugKotlin
, which should be faster, to generate all the Destinations. With the above annotated composable, a ProfileScreenDestination
file (that we'll use in step 4) would be generated.
4. Use the generated Destination invoke method to navigate to itβ
It will have the correct typed arguments.
@RootNavGraph(start = true) // sets this as the start destination of the default nav graph
@Destination
@Composable
fun HomeScreen(
navigator: DestinationsNavigator
) {
/*...*/
navigator.navigate(ProfileScreenDestination(id = 7, groupName = "Kotlin programmers"))
}
DestinationsNavigator is a wrapper interface to NavController that if declared as a parameter, will be provided for free by the library. NavController can also be provided in the exact same way, but it ties your composables to a specific implementation which will make it harder to test and preview. Read more here
5. Finally, add the NavHost callβ
DestinationsNavHost(navGraph = NavGraphs.root)
NavGraphs
is a generated file that describes your navigation graphs and their destinations. By default all destinations will belong to "root" (@RootNavGraph), but you can create your own nav graphs annotations to have certain screens in other navigation graphs.
This call adds all annotated Composable functions as destinations of the Navigation Host.
That's it! No need to worry about routes, NavTypes, bundles and strings. All that redundant and error-prone code gets generated for you.