0
# Koin Compose
1

2
Koin Compose provides seamless integration between the Koin dependency injection framework and Jetpack Compose for Kotlin Multiplatform development. It offers Compose-aware APIs for dependency injection, application setup, scope management, and module loading with full support for Compose lifecycle management.
3

4
## Package Information
5

6
- **Package Name**: koin-compose-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("io.insert-koin:koin-compose-jvm:4.1.1")`
10
- **Platforms**: Android, JVM, JavaScript, Native (iOS/macOS), WASM-JS
11

12
## Core Imports
13

14
```kotlin
15
import org.koin.compose.*
16
```
17

18
For specific functionality:
19

20
```kotlin
21
import org.koin.compose.KoinApplication
22
import org.koin.compose.KoinIsolatedContext
23
import org.koin.compose.KoinApplicationPreview
24
import org.koin.compose.koinInject
25
import org.koin.compose.getKoin
26
import org.koin.compose.currentKoinScope
27
import org.koin.compose.KoinScope
28
import org.koin.compose.rememberKoinScope
29
import org.koin.compose.rememberKoinModules
30
```
31

32
## Basic Usage
33

34
```kotlin
35
@Composable
36
fun App() {
37
    KoinApplication(application = {
38
        // Configure Koin modules
39
        modules(appModule)
40
    }) {
41
        // Your Compose UI
42
        MainScreen()
43
    }
44
}
45

46
@Composable  
47
fun MainScreen() {
48
    // Inject dependencies directly in Composables
49
    val repository: UserRepository = koinInject()
50
    val service: ApiService = koinInject(qualifier = named("api"))
51
    
52
    // Use injected dependencies
53
    LaunchedEffect(Unit) {
54
        val users = repository.getUsers()
55
        // ...
56
    }
57
}
58

59
// Alternative: Using isolated context for modular features
60
@Composable
61
fun FeatureModule() {
62
    val isolatedApp = koinApplication {
63
        modules(featureModule)
64
    }
65
    
66
    KoinIsolatedContext(context = isolatedApp) {
67
        FeatureContent()
68
    }
69
}
70
```
71

72
## Architecture
73

74
Koin Compose is built around several key components:
75

76
- **Application Context Management**: Provides Koin application and scope contexts throughout the Compose hierarchy using Composition Locals
77
- **Lifecycle Integration**: Automatic cleanup of scopes and modules when Compose components are forgotten or abandoned
78
- **Multiplatform Support**: Platform-specific optimizations for Android (context injection) and other platforms
79
- **Experimental APIs**: Advanced features for scope and module management with `@KoinExperimentalAPI`
80
- **Compose State Integration**: Uses `remember` for state management and follows Compose recomposition patterns
81

82
## Capabilities
83

84
### Application Setup
85

86
Core functions for setting up Koin contexts within Compose applications, including both standard and multiplatform configurations.
87

88
```kotlin { .api }
89
@Composable
90
fun KoinApplication(
91
    application: KoinAppDeclaration,
92
    content: @Composable () -> Unit
93
)
94

95
@Composable  
96
@KoinExperimentalAPI
97
fun KoinMultiplatformApplication(
98
    config: KoinConfiguration,
99
    logLevel: Level = Level.INFO,
100
    content: @Composable () -> Unit
101
)
102

103
@Composable
104
fun KoinIsolatedContext(
105
    context: KoinApplication,
106
    content: @Composable () -> Unit
107
)
108

109
@Composable
110
fun KoinApplicationPreview(
111
    application: KoinAppDeclaration,
112
    content: @Composable () -> Unit
113
)
114
```
115

116
[Application Setup](./application-setup.md)
117

118
### Dependency Injection
119

120
Type-safe dependency resolution functions that integrate with Compose recomposition and support parameters, qualifiers, and scopes.
121

122
```kotlin { .api }
123
@Composable
124
inline fun <reified T> koinInject(
125
    qualifier: Qualifier? = null,
126
    scope: Scope = currentKoinScope()
127
): T
128

129
@Composable
130
inline fun <reified T> koinInject(
131
    qualifier: Qualifier? = null,
132
    scope: Scope = currentKoinScope(),
133
    noinline parameters: ParametersDefinition
134
): T
135

136
@Composable
137
inline fun <reified T> koinInject(
138
    qualifier: Qualifier? = null,
139
    scope: Scope = currentKoinScope(),
140
    parametersHolder: ParametersHolder
141
): T
142
```
143

144
[Dependency Injection](./dependency-injection.md)
145

146
### Context Access
147

148
Functions to retrieve current Koin application and scope contexts from anywhere in the Compose hierarchy.
149

150
```kotlin { .api }
151
@Composable
152
fun getKoin(): Koin
153

154
@Composable
155
fun currentKoinScope(): Scope
156
```
157

158
[Context Access](./context-access.md)
159

160
### Scope Management
161

162
Experimental APIs for creating and managing Koin scopes with automatic lifecycle management tied to Compose recomposition.
163

164
```kotlin { .api }
165
@KoinExperimentalAPI
166
@Composable
167
fun KoinScope(
168
    scopeDefinition: Koin.() -> Scope,
169
    content: @Composable () -> Unit
170
)
171

172
@KoinExperimentalAPI
173
@Composable
174
inline fun <reified T : Any> KoinScope(
175
    scopeID: ScopeID,
176
    noinline content: @Composable () -> Unit
177
)
178

179
@KoinExperimentalAPI
180
@Composable
181
fun KoinScope(
182
    scopeID: ScopeID,
183
    scopeQualifier: Qualifier,
184
    content: @Composable () -> Unit
185
)
186

187
@KoinExperimentalAPI
188
@Composable
189
fun rememberKoinScope(scope: Scope): Scope
190
```
191

192
[Scope Management](./scope-management.md)
193

194
### Module Management
195

196
Experimental API for dynamically loading and unloading Koin modules based on Compose lifecycle events.
197

198
```kotlin { .api }
199
@KoinExperimentalAPI
200
@Composable
201
inline fun rememberKoinModules(
202
    unloadOnForgotten: Boolean? = null,
203
    unloadOnAbandoned: Boolean? = null,
204
    unloadModules: Boolean = false,
205
    crossinline modules: @DisallowComposableCalls () -> List<Module> = { emptyList() }
206
)
207
```
208

209
[Module Management](./module-management.md)
210

211
## Types
212

213
### Core Types
214

215
```kotlin { .api }
216
/** Exception thrown when Koin Context is not found */
217
class UnknownKoinContext : Exception()
218

219
/** Parameters holder for dependency injection */
220
class ParametersHolder
221

222
/** Parameters definition function type */
223
typealias ParametersDefinition = () -> ParametersHolder
224

225
/** Scope identifier type */
226
typealias ScopeID = String
227
```
228

229
### Composition Locals
230

231
```kotlin { .api }
232
/** Provides Koin application context throughout Compose hierarchy */
233
val LocalKoinApplication: ProvidableCompositionLocal<ComposeContextWrapper<Koin>>
234

235
/** Provides Koin scope context throughout Compose hierarchy */  
236
val LocalKoinScope: ProvidableCompositionLocal<ComposeContextWrapper<Scope>>
237
```
238

239
## Error Handling
240

241
The library throws `UnknownKoinContext` when attempting to access Koin contexts that haven't been properly initialized through `KoinApplication` or related setup functions.
242

243
```kotlin
244
try {
245
    val koin = getKoin()
246
} catch (e: UnknownKoinContext) {
247
    // Handle missing Koin context
248
}
249
```
250

251
## Platform-Specific Behavior
252

253
### Android
254
- Automatically injects `LocalContext.current.applicationContext` into Koin application
255
- Uses Android-specific logging
256
- Integrates with Android Activity/Fragment lifecycle
257

258
### Other Platforms (JVM, JS, Native, WASM-JS)
259
- Uses print-based logging
260
- Standard Koin platform initialization
261
- Full Kotlin Multiplatform compatibility
262

263
## API Stability
264

265
- **Stable**: Core dependency injection, application setup, context access
266
- **Experimental** (`@KoinExperimentalAPI`): Scope management, module management, multiplatform application setup
267
- **Deprecated**: `KoinContext` function (no longer needed with modern Compose integration)