
Reports network online/offline state and emits changes as a cold Flow; includes Koin module and factory functions, validates reachability where available, and supports trivial test fakes.
A small Kotlin Multiplatform library that tells your app whether the device is online, and lets it react when that changes. Use it to pause sync while offline, show an "offline" banner, or retry a request when the connection comes back. It has no UI and doesn't depend on Compose. It comes with a Koin module, and plain factory functions for apps that don't use Koin (see Without Koin).
class Synchronizer(
private val networkConnectivityObserver: NetworkConnectivityObserver,
) {
suspend fun pushWhenOnline() {
networkConnectivityObserver.observe()
.filter { isConnected -> isConnected }
.collect { push() }
}
}"Online" means something slightly different on each platform. Only Android checks that the internet is actually reachable; see What counts as connected.
| Platform | Targets | Minimum |
|---|---|---|
| Android | android |
minSdk 23 |
| JVM (desktop, server) | jvm |
Java 11 |
| iOS |
iosArm64, iosSimulatorArm64
|
|
| macOS | macosArm64 |
|
| Linux |
linuxX64, linuxArm64
|
|
| Browser |
js, wasmJs
|
There are no Intel Apple targets (iosX64, macosX64), no watchOS, tvOS or Windows. The js and wasmJs artifacts
also declare Node.js, which has no navigator.onLine, so there the observer always reports connected.
The library is on Maven Central, so mavenCentral() in your repositories is enough.
dependencies {
implementation("software.quare:connectivity:1.2.0")
}Or with a version catalog:
[versions]
quare-connectivity = "1.2.0"
[libraries]
quare-connectivity = { module = "software.quare:connectivity", version.ref = "quare-connectivity" }implementation(libs.quare.connectivity)In a multiplatform project, add it to commonMain. It brings koin-core 4.2.2 and kotlinx-coroutines-core 1.11.0
with it as API dependencies, so your app gets at least those versions. It is built with Kotlin 2.4.21.
On Android there is nothing to add to your manifest: the library's manifest declares the ACCESS_NETWORK_STATE
permission and the build merges it into your app. It is a normal permission, so there is no runtime prompt.
Load connectivityModule when starting Koin:
import software.quare.connectivity.connectivityModule
startKoin {
androidContext(application) // Android only
modules(connectivityModule)
}On Android the module needs the application Context from Koin. androidContext() comes from
io.insert-koin:koin-android, which this library does not bring; add it to your Android app if you don't have it yet.
Create the instances yourself with the factory functions, the same ones connectivityModule uses:
import software.quare.connectivity.IsConnected
import software.quare.connectivity.NetworkConnectivityObserver
import software.quare.connectivity.createIsConnected
import software.quare.connectivity.createNetworkConnectivityObserver
val networkConnectivityObserver: NetworkConnectivityObserver = createNetworkConnectivityObserver()
val isConnected: IsConnected = createIsConnected(networkConnectivityObserver)On Android, createNetworkConnectivityObserver takes a Context; it only uses the application context, so passing an
Activity is fine:
val networkConnectivityObserver = createNetworkConnectivityObserver(context)createNetworkConnectivityObserver is declared per platform (with a Context on Android, without one elsewhere), so
in a multiplatform project call it from platform code, or from an expect/actual of your own, and pass the observer
to common code. koin-core still comes along as a dependency, but nothing starts Koin unless you do.
The module provides two things, both in the software.quare.connectivity package:
val observer: NetworkConnectivityObserver = get()
observer.observe() // Flow<Boolean>: the current state first, then every change
val isConnected: IsConnected = get()
if (isConnected()) fetch() // one-off check; suspends until the platform reports the current stateFrom the module, NetworkConnectivityObserver is a single instance; IsConnected is created on each request and reads the first value
of observe().
observe() returns a cold flow that never completes. Collect it in a scope that ends, or turn it into a StateFlow:
class SyncViewModel(
networkConnectivityObserver: NetworkConnectivityObserver,
) : ViewModel() {
val isOnline: StateFlow<Boolean> = networkConnectivityObserver
.observe()
.stateIn(
scope = viewModelScope,
started = SharingStarted.WhileSubscribed(5_000),
initialValue = true, // assume online until the platform answers, so an offline banner doesn't flash
)
}
@Composable
fun SyncScreen(viewModel: SyncViewModel) {
val isOnline by viewModel.isOnline.collectAsState() // or collectAsStateWithLifecycle()
if (!isOnline) OfflineBanner()
}NWPathMonitor, or a polling loop) and stops it when the collecting coroutine is cancelled.stateIn or shareIn as above.| Platform |
true when |
Updates |
|---|---|---|
| Android | Some network, not only the default one, has internet access and Android validated it (its own connectivity check passed). A captive portal or a Wi-Fi without internet counts as disconnected. The first value follows the same rule as the updates | Pushed by ConnectivityManager
|
| iOS, macOS | The NWPathMonitor path is satisfied: there is a usable network route. It doesn't check that the internet is reachable |
Pushed by the Network framework |
| JVM | Some network interface other than loopback is up. Virtual interfaces (VPN, Docker, VMs) count, and so does a local network without internet. If the interfaces can't be read, it counts as connected | Checked every 3 seconds |
| Linux | Some network interface other than loopback has the operstate "up" in /sys/class/net. A local network without internet counts. If that directory can't be read, as in some sandboxes, it counts as connected |
Checked every 3 seconds |
| Browser (JS, Wasm/JS) |
navigator.onLine is true, which the browser reports for any network, even one without internet. Without navigator.onLine, as on Node.js, it counts as connected |
Checked every 3 seconds |
If you need to know that your own server answers, make the request and handle the failure; this library only tells you when trying is pointless or when it is worth retrying.
There is no separate testing artifact. Both types are fun interfaces, so a fake takes one line:
val alwaysOnline = NetworkConnectivityObserver { flowOf(true) }
val offline = IsConnected { false }To drive changes from a test, back the fake with a MutableStateFlow:
val online = MutableStateFlow(true)
val observer = NetworkConnectivityObserver { online }
online.value = false // collectors now see false./gradlew allTests # every target (Apple targets need macOS, the Linux tests a Linux host)
./scripts/ktlint.sh # ktlint with github.com/Quartel-Enterprise/ktlint-rules (--format to fix)
./gradlew publishToMavenLocal # try a change in an app before releasing itBuilding needs the Android SDK: set ANDROID_HOME or sdk.dir in local.properties.
version in build.gradle.kts and merge it to main.1.2.3). The Publish workflow checks the tag, runs the
tests and releases the signed artifacts to Maven Central, where they show up a few minutes later.A small Kotlin Multiplatform library that tells your app whether the device is online, and lets it react when that changes. Use it to pause sync while offline, show an "offline" banner, or retry a request when the connection comes back. It has no UI and doesn't depend on Compose. It comes with a Koin module, and plain factory functions for apps that don't use Koin (see Without Koin).
class Synchronizer(
private val networkConnectivityObserver: NetworkConnectivityObserver,
) {
suspend fun pushWhenOnline() {
networkConnectivityObserver.observe()
.filter { isConnected -> isConnected }
.collect { push() }
}
}"Online" means something slightly different on each platform. Only Android checks that the internet is actually reachable; see What counts as connected.
| Platform | Targets | Minimum |
|---|---|---|
| Android | android |
minSdk 23 |
| JVM (desktop, server) | jvm |
Java 11 |
| iOS |
iosArm64, iosSimulatorArm64
|
|
| macOS | macosArm64 |
|
| Linux |
linuxX64, linuxArm64
|
|
| Browser |
js, wasmJs
|
There are no Intel Apple targets (iosX64, macosX64), no watchOS, tvOS or Windows. The js and wasmJs artifacts
also declare Node.js, which has no navigator.onLine, so there the observer always reports connected.
The library is on Maven Central, so mavenCentral() in your repositories is enough.
dependencies {
implementation("software.quare:connectivity:1.2.0")
}Or with a version catalog:
[versions]
quare-connectivity = "1.2.0"
[libraries]
quare-connectivity = { module = "software.quare:connectivity", version.ref = "quare-connectivity" }implementation(libs.quare.connectivity)In a multiplatform project, add it to commonMain. It brings koin-core 4.2.2 and kotlinx-coroutines-core 1.11.0
with it as API dependencies, so your app gets at least those versions. It is built with Kotlin 2.4.21.
On Android there is nothing to add to your manifest: the library's manifest declares the ACCESS_NETWORK_STATE
permission and the build merges it into your app. It is a normal permission, so there is no runtime prompt.
Load connectivityModule when starting Koin:
import software.quare.connectivity.connectivityModule
startKoin {
androidContext(application) // Android only
modules(connectivityModule)
}On Android the module needs the application Context from Koin. androidContext() comes from
io.insert-koin:koin-android, which this library does not bring; add it to your Android app if you don't have it yet.
Create the instances yourself with the factory functions, the same ones connectivityModule uses:
import software.quare.connectivity.IsConnected
import software.quare.connectivity.NetworkConnectivityObserver
import software.quare.connectivity.createIsConnected
import software.quare.connectivity.createNetworkConnectivityObserver
val networkConnectivityObserver: NetworkConnectivityObserver = createNetworkConnectivityObserver()
val isConnected: IsConnected = createIsConnected(networkConnectivityObserver)On Android, createNetworkConnectivityObserver takes a Context; it only uses the application context, so passing an
Activity is fine:
val networkConnectivityObserver = createNetworkConnectivityObserver(context)createNetworkConnectivityObserver is declared per platform (with a Context on Android, without one elsewhere), so
in a multiplatform project call it from platform code, or from an expect/actual of your own, and pass the observer
to common code. koin-core still comes along as a dependency, but nothing starts Koin unless you do.
The module provides two things, both in the software.quare.connectivity package:
val observer: NetworkConnectivityObserver = get()
observer.observe() // Flow<Boolean>: the current state first, then every change
val isConnected: IsConnected = get()
if (isConnected()) fetch() // one-off check; suspends until the platform reports the current stateFrom the module, NetworkConnectivityObserver is a single instance; IsConnected is created on each request and reads the first value
of observe().
observe() returns a cold flow that never completes. Collect it in a scope that ends, or turn it into a StateFlow:
class SyncViewModel(
networkConnectivityObserver: NetworkConnectivityObserver,
) : ViewModel() {
val isOnline: StateFlow<Boolean> = networkConnectivityObserver
.observe()
.stateIn(
scope = viewModelScope,
started = SharingStarted.WhileSubscribed(5_000),
initialValue = true, // assume online until the platform answers, so an offline banner doesn't flash
)
}
@Composable
fun SyncScreen(viewModel: SyncViewModel) {
val isOnline by viewModel.isOnline.collectAsState() // or collectAsStateWithLifecycle()
if (!isOnline) OfflineBanner()
}NWPathMonitor, or a polling loop) and stops it when the collecting coroutine is cancelled.stateIn or shareIn as above.| Platform |
true when |
Updates |
|---|---|---|
| Android | Some network, not only the default one, has internet access and Android validated it (its own connectivity check passed). A captive portal or a Wi-Fi without internet counts as disconnected. The first value follows the same rule as the updates | Pushed by ConnectivityManager
|
| iOS, macOS | The NWPathMonitor path is satisfied: there is a usable network route. It doesn't check that the internet is reachable |
Pushed by the Network framework |
| JVM | Some network interface other than loopback is up. Virtual interfaces (VPN, Docker, VMs) count, and so does a local network without internet. If the interfaces can't be read, it counts as connected | Checked every 3 seconds |
| Linux | Some network interface other than loopback has the operstate "up" in /sys/class/net. A local network without internet counts. If that directory can't be read, as in some sandboxes, it counts as connected |
Checked every 3 seconds |
| Browser (JS, Wasm/JS) |
navigator.onLine is true, which the browser reports for any network, even one without internet. Without navigator.onLine, as on Node.js, it counts as connected |
Checked every 3 seconds |
If you need to know that your own server answers, make the request and handle the failure; this library only tells you when trying is pointless or when it is worth retrying.
There is no separate testing artifact. Both types are fun interfaces, so a fake takes one line:
val alwaysOnline = NetworkConnectivityObserver { flowOf(true) }
val offline = IsConnected { false }To drive changes from a test, back the fake with a MutableStateFlow:
val online = MutableStateFlow(true)
val observer = NetworkConnectivityObserver { online }
online.value = false // collectors now see false./gradlew allTests # every target (Apple targets need macOS, the Linux tests a Linux host)
./scripts/ktlint.sh # ktlint with github.com/Quartel-Enterprise/ktlint-rules (--format to fix)
./gradlew publishToMavenLocal # try a change in an app before releasing itBuilding needs the Android SDK: set ANDROID_HOME or sdk.dir in local.properties.
version in build.gradle.kts and merge it to main.1.2.3). The Publish workflow checks the tag, runs the
tests and releases the signed artifacts to Maven Central, where they show up a few minutes later.