0
# Koin Compose 
1

2
Koin Compose provides seamless integration between the Koin dependency injection framework and Jetpack Compose, offering Compose-specific APIs for dependency injection in Android Compose applications. It enables developers to inject dependencies directly into Composable functions and manage application-wide dependency injection context within Compose applications.
3

4
## Package Information
5

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

12
## Core Imports
13

14
```kotlin
15
import org.koin.compose.*
16
import org.koin.compose.scope.*
17
import org.koin.compose.module.*
18
```
19

20
## Basic Usage
21

22
```kotlin
23
import androidx.compose.runtime.Composable
24
import org.koin.compose.KoinApplication
25
import org.koin.compose.koinInject
26
import org.koin.core.context.startKoin
27
import org.koin.dsl.module
28

29
// Define your dependencies
30
val appModule = module {
31
    single<UserRepository> { UserRepositoryImpl() }
32
    single<UserService> { UserServiceImpl(get()) }
33
}
34

35
// Setup Koin in your app
36
@Composable 
37
fun App() {
38
    KoinApplication(
39
        application = {
40
            modules(appModule)
41
        }
42
    ) {
43
        UserScreen()
44
    }
45
}
46

47
// Inject dependencies in Composables
48
@Composable
49
fun UserScreen() {
50
    val userService: UserService = koinInject()
51
    // Use userService...
52
}
53
```
54

55
## Architecture
56

57
Koin Compose is built around several key components:
58

59
- **Composition Locals**: Integration with Compose's CompositionLocal system for context propagation
60
- **Lifecycle Management**: Automatic handling of Koin contexts and scopes tied to Compose lifecycle
61
- **Platform Abstraction**: Multiplatform support with platform-specific configurations
62
- **Remember Integration**: Performance optimization using Compose's remember system
63
- **Scope Integration**: Support for Koin scopes with automatic cleanup
64

65
## Capabilities
66

67
### Application Setup
68

69
Core composable functions for setting up Koin dependency injection within Compose applications, including basic setup, multiplatform configuration, and isolated contexts.
70

71
```kotlin { .api }
72
@Composable
73
fun KoinApplication(
74
    application: KoinAppDeclaration,
75
    content: @Composable () -> Unit
76
)
77

78
@Composable
79
@KoinExperimentalAPI  
80
fun KoinMultiplatformApplication(
81
    config: KoinConfiguration,
82
    logLevel: Level = Level.INFO,
83
    content: @Composable () -> Unit
84
)
85

86
@Composable
87
fun KoinIsolatedContext(
88
    context: KoinApplication,
89
    content: @Composable () -> Unit
90
)
91
```
92

93
[Application Setup](./application-setup.md)
94

95
### Dependency Injection
96

97
Functions for injecting dependencies into Composable functions with type safety and performance optimization through Compose's remember system.
98

99
```kotlin { .api }
100
@Composable
101
inline fun <reified T> koinInject(
102
    qualifier: Qualifier? = null,
103
    scope: Scope = currentKoinScope()
104
): T
105

106
@Composable
107
inline fun <reified T> koinInject(
108
    qualifier: Qualifier? = null,
109
    scope: Scope = currentKoinScope(),
110
    noinline parameters: ParametersDefinition
111
): T
112

113
@Composable
114
inline fun <reified T> koinInject(
115
    qualifier: Qualifier? = null,
116
    scope: Scope = currentKoinScope(),
117
    parametersHolder: ParametersHolder
118
): T
119
```
120

121
[Dependency Injection](./dependency-injection.md)
122

123
### Context Access
124

125
Functions for accessing the current Koin application instance and scope within Compose functions, with automatic fallback to default contexts.
126

127
```kotlin { .api }
128
@Composable
129
fun getKoin(): Koin
130

131
@Composable  
132
fun currentKoinScope(): Scope
133
```
134

135
[Context Access](./context-access.md)
136

137
### Scope Management
138

139
Advanced scope management capabilities allowing creation and management of Koin scopes with automatic lifecycle handling tied to Compose composition lifecycle.
140

141
```kotlin { .api }
142
@Composable
143
@KoinExperimentalAPI
144
fun KoinScope(
145
    scopeDefinition: Koin.() -> Scope,
146
    content: @Composable () -> Unit
147
)
148

149
@Composable
150
@KoinExperimentalAPI
151
inline fun <reified T : Any> KoinScope(
152
    scopeID: ScopeID,
153
    content: @Composable () -> Unit
154
)
155

156
@Composable
157
@KoinExperimentalAPI  
158
fun rememberKoinScope(scope: Scope): Scope
159
```
160

161
[Scope Management](./scope-management.md)
162

163
### Module Management
164

165
Dynamic module loading and unloading capabilities with integration into Compose lifecycle for automatic cleanup.
166

167
```kotlin { .api }
168
@Composable
169
@KoinExperimentalAPI
170
inline fun rememberKoinModules(
171
    unloadOnForgotten: Boolean? = null,
172
    unloadOnAbandoned: Boolean? = null, 
173
    unloadModules: Boolean = false,
174
    crossinline modules: @DisallowComposableCalls () -> List<Module> = { emptyList() }
175
)
176
```
177

178
[Module Management](./module-management.md)
179

180
## Core Types
181

182
```kotlin { .api }
183
// Composition locals for Koin context
184
val LocalKoinApplication: ProvidableCompositionLocal<Koin>
185
val LocalKoinScope: ProvidableCompositionLocal<Scope>
186

187
// Type aliases from Koin core and compose
188
typealias KoinAppDeclaration = KoinApplication.() -> Unit
189
typealias ParametersDefinition = () -> ParametersHolder
190
typealias ScopeID = String
191

192
// Core Koin types (from koin-core)
193
interface Koin {
194
    val scopeRegistry: ScopeRegistry
195
    val logger: Logger
196
    fun <T : Any> get(clazz: KClass<T>, qualifier: Qualifier? = null): T
197
    fun <T : Any> getOrCreateScope(scopeId: String, qualifier: Qualifier? = null): Scope
198
    fun <T : Any> createScope(scopeId: String): Scope
199
    inline fun <reified T : Any> getOrCreateScope(scopeId: String): Scope
200
}
201

202
interface Scope {
203
    val id: String
204
    val isRoot: Boolean
205
    val closed: Boolean
206
    val logger: Logger
207
    fun <T : Any> get(clazz: KClass<T>, qualifier: Qualifier? = null): T
208
    fun <T : Any> getWithParameters(clazz: KClass<T>, qualifier: Qualifier?, parameters: ParametersHolder): T
209
    fun close()
210
}
211

212
interface KoinApplication {
213
    val koin: Koin
214
}
215

216
interface KoinConfiguration
217

218
class ParametersHolder
219

220
interface Qualifier
221

222
class StringQualifier(val value: String) : Qualifier
223

224
// Qualifier factory functions (from koin-core)
225
fun named(name: String): Qualifier
226
inline fun <reified T> named(): Qualifier
227

228
interface Module
229

230
enum class Level { NONE, ERROR, INFO, DEBUG }
231

232
// Lifecycle management interfaces
233
interface RememberObserver {
234
    fun onRemembered()
235
    fun onForgotten() 
236
    fun onAbandoned()
237
}
238

239
// Platform abstraction
240
object KoinPlatform {
241
    fun getKoin(): Koin
242
    fun getKoinOrNull(): Koin?
243
}
244
```
245

246
## Platform-Specific Features
247

248
### Android
249
- Automatic Android context injection via `LocalContext.current`  
250
- Android logger integration with `androidLogger()`
251
- Application context discovery for Koin components
252

253
### JVM/Desktop  
254
- Print logger for desktop applications
255
- Standard Koin platform integration
256

257
### JavaScript/WebAssembly
258
- Browser and Node.js compatibility
259
- Print logger for web environments  
260

261
### Native (iOS/macOS)
262
- Native platform support
263
- Print logger for native applications
264

265
## Error Handling
266

267
```kotlin { .api }
268
class UnknownKoinContext : Exception()
269
```
270

271
Common error scenarios and exceptions from Koin core:
272
- `KoinApplicationAlreadyStartedException`: When trying to start Koin when already started
273
- `UnknownKoinContext`: When Koin context cannot be found in Compose composition
274
- `ClosedScopeException`: When accessing a closed scope
275
- `NoBeanDefFoundException`: When requested dependency is not defined in Koin modules
276
- `ScopeAlreadyCreatedException`: When trying to create a scope that already exists
277
- `ParameterException`: When required parameters are missing or incorrect
278
- Configuration errors in multiplatform setup (missing Android context, logger setup failures)