Detects internet reachability and streams status changes via reactive flows; singleton entry, validated connectivity (avoids captive-portal false positives), synchronous shortcuts and test fakes.
A Kotlin Multiplatform library that tells you whether the device is on the internet and lets you observe changes as they happen, behind one API:
nw_path_monitor (via Kotlin/Native cinterop), serving the same code
path on all three platforms.ConnectivityManager.NetworkCallback
registered against NET_CAPABILITY_INTERNET + NET_CAPABILITY_VALIDATED,
so captive portals correctly register as not reachable.UI is out of scope — Reachable is the headless :reachable KMP module
(CLAUDE.md §1). Each platform app consumes it natively.
Reachability.shared is the recommended entry point: a process-lifetime
singleton with no Context plumbing. On Android, the library's bundled
androidx.startup initializer attaches it before Application.onCreate.
On Apple, first access constructs the nw_path_monitor eagerly and starts
observing immediately. The explicit-lifecycle factories
(Reachability(context) / Reachability()) remain available for tests
and any code that wants per-instance teardown.
Native targets are ARM-only: iosArm64, iosSimulatorArm64, macosArm64,
Android arm64-v8a. A jvm target (architecture-neutral JVM 21 bytecode)
covers desktop and server JVMs. SKIE bridges the Swift surface — enums
become exhaustive Swift enums, becomes ,
becomes .
The full mkdocs site is published to happycodelucky.github.io/reachable. Highlights:
Reachable publishes to Maven Central. From a Kotlin Multiplatform project,
depend on :reachable from commonMain — KMP resolves the right per-target
slice (Android AAR, JVM jar, iosArm64, iosSimulatorArm64, macosArm64)
for you:
// shared/build.gradle.kts
kotlin {
sourceSets {
commonMain.dependencies {
implementation("com.happycodelucky.reachable:reachable:0.12.11")
}
}
}
Android-only and JVM-only consumers depend on the artifact directly:
// app/build.gradle.kts
dependencies {
implementation("com.happycodelucky.reachable:reachable:0.12.11")
}
Pure-Swift apps (no Kotlin toolchain) consume Reachable via Swift Package
Manager instead — a prebuilt, SKIE-enhanced Reachable.xcframework attached
to each GitHub Release:
// Package.swift — or Xcode: File → Add Package Dependencies…
dependencies: [
.package(url: "https://github.com/happycodelucky/reachable.git", from: "0.12.11"),
]
A companion reachable-testing artifact ships FakeReachability and the
withFakeReachability { } helper — add it as a test dependency at the same
version (Maven Central only; no SPM distribution). See the
Installation guide
for platform floors, the testing artifact, and the local-development
override.
// Singleton path — no Context plumbing, no construction boilerplate.
val reachability: Reachability = Reachability.shared
if (reachability.isReachable) {
// online
}
reachability.status.collect { status ->
// every state change
}
// close() on .shared is a no-op — the singleton lives for the process.
From Swift:
let reachability: any Reachability = Reachability.shared
For explicit-lifecycle needs (tests, per-feature observers):
// Android
val r: Reachability = Reachability(applicationContext)
// JVM (desktop / server) — optional poll cadence, default 5 seconds
val r: Reachability = Reachability(pollInterval = 10.seconds)
// Apple
val r: any Reachability = Reachability()
r.close() // honours close() normally
status.value for a synchronous read, status.collect {} for a reactive
listener, status.first() for a one-shot suspend.
The same appleMain factory covers all three platforms. Use
Reachability.shared for zero-setup access:
For explicit-lifecycle code (tests or per-feature observers), use the
top-level factory and call close() on teardown:
@main
struct MyApp: App {
private let reachability: any Reachability = Reachability()
var body: some Scene {
WindowGroup {
ContentView()
.environmentObject(ConnectivityModel(reachability: reachability))
}
}
}
nw_path_monitor doesn't require any entitlement. The network.client
sandbox entitlement on macOS is about the app's own outgoing traffic, not
the reachability check.
The library bundles an androidx.startup initializer that attaches
Reachability.shared to the application Context automatically during
the InitializationProvider ContentProvider pass — before
Application.onCreate. No setup required:
import com.happycodelucky.reachable.Reachability
// No Application subclass, no Context plumbing needed.
@Composable
fun ConnectivityBanner() {
val status by Reachability.shared.status.collectAsStateWithLifecycle()
if (!status.isReachable) {
Text("You're offline")
}
}
If you disable InitializationProvider entirely (rare), or need explicit
lifecycle control, use the factory instead:
class MyApp : Application() {
lateinit var reachability: Reachability
override fun onCreate() {
super.onCreate()
reachability = Reachability(applicationContext)
}
override fun onTerminate() {
reachability.close()
super.onTerminate()
}
}
android.permission.ACCESS_NETWORK_STATE is declared in the library's own
AndroidManifest.xml and merged into your app at build time. It's a
normal-protection permission, so no runtime grant is needed.
No Context, no initializer — Reachability.shared starts the interface
poll loop on first access, exactly like Apple:
import com.happycodelucky.reachable.Reachability
val reachability = Reachability.shared
reachability.status.collect { status ->
// re-rendered every time an interface comes up or goes down
}
For explicit lifecycle (or a custom poll cadence), use the factory:
import kotlin.time.Duration.Companion.seconds
val reachability = Reachability(pollInterval = 10.seconds) // default 5.seconds
// ...
reachability.close() // stops the poll loop
Know the trade-offs on this platform: the JDK offers no validation probe,
so isReachable means "a non-loopback interface is up with a routable
address" — a captive portal still reads as reachable. Changes surface
within one poll tick rather than milliseconds, isDataMetered is always
false, and transport classification is inferred from interface names
(Transport.Other when ambiguous — e.g. macOS's en0).
Apple's Low Data Mode signal (nw_path_is_constrained) folds into
isDataMetered alongside nw_path_is_expensive; there's no separate
"Low Data Mode" axis in the public API.
The two most-asked questions get dedicated properties so callers don't
unpack status.value for a one-line read:
reachability.isReachable // sync online check
reachability.isDataMetered // sync metered-path check
reachability.reachable // StateFlow<Boolean>, conflated, online/offline only
reachability.dataMetered // StateFlow<Boolean>, conflated, metered/unmetered only
The reactive variants are dedicated MutableStateFlows the library
updates synchronously alongside status — transport-only changes don't
trigger emissions on reachable or dataMetered.
A companion artifact ships test fakes so consumers can drive
Reachability.shared in unit tests without a live platform observer:
// shared/build.gradle.kts
kotlin {
sourceSets {
commonTest.dependencies {
implementation("com.happycodelucky.reachable:reachable-testing:VERSION")
}
}
}
Then from any test:
@Test
fun deviceIsOnline() = runTest {
withFakeReachability(
initial = ReachabilityStatus(
isReachable = true,
transport = Transport.Wifi,
isDataMetered = false,
),
) { fake ->
val vm = MyViewModel() // reads Reachability.shared
assertTrue(vm.online)
fake.setReachable(false)
assertFalse(vm.online)
}
}
withFakeReachability installs the fake as Reachability.shared,
runs the block, then uninstalls and closes the fake in finally — even
when the block throws. See Installation
for the full dependency snippet and the Gradle coordinate.
mise pins JDK, Gradle, Python, xcodegen, gh,
and the Swift tooling. Bootstrap once per machine:
brew install mise
mise trust # accept mise.toml in this checkout
mise install # provision every tool at the pinned version
Then the task surface:
mise run check # ktlint + all unit tests (iOS sim, macOS, Android host, JVM)
mise run build:ios # iOS device + simulator debug frameworks
mise run build:macos # macOS desktop debug framework
mise run build # release Reachable.xcframework (sample-app local SPM)
mise run build:android # Android AAR
mise run open:ios # spm:dev + xcodegen + open apps/ios in Xcode
mise run open:macos # spm:dev + xcodegen + open apps/macos in Xcode
Each task is a thin wrapper over ./gradlew (or xcodegen for the
open:* tasks); see mise.toml for the exact mapping, or
run mise tasks to list everything. Raw ./gradlew invocations still
work — mise just ensures everyone (and CI) runs the same versions.
For the iOS and macOS sample apps see apps/ios/README.md
and apps/macos/README.md.
See CLAUDE.md for the full project conventions.
Reachable is released under the Apache License 2.0.
Copyright 2026 Paul Bates
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
java.net.NetworkInterface.
Best-effort — the JDK has no validation probe, so captive portals are
not detected and transport is inferred from interface names.StateFlow<T>AsyncSequence<T>suspend funasync throwsReachability.Result.INTERNET + VALIDATED, wired-Ethernet mapping, captive portals.import Reachable
final class ConnectivityModel {
var status: ReachabilityStatus = ReachabilityStatus.companion.Unknown
private var task: Task<Void, Never>?
init() {
// Reachability.shared — process-lifetime singleton, no close needed.
let reachability: any Reachability = Reachability.shared
task = Task { [weak self] in
for await s in reachability.status { self?.status = s }
}
}
deinit { task?.cancel() }
}
| iOS / iPadOS | macOS | Android | JVM (desktop / server) |
|---|
| Reachability backend | nw_path_monitor (satisfied) | nw_path_monitor (satisfied) | NetworkCallback (INTERNET + VALIDATED) | NetworkInterface polling (best-effort) |
| Captive-portal handling | OS-internal probe | OS-internal probe | NET_CAPABILITY_VALIDATED | not detected |
Transport.Wifi / Cellular | yes | yes | yes | best-effort (interface names) |
Transport.Ethernet | yes (USB-C / dock adapters) | yes (nw_interface_type_wired) | yes (TRANSPORT_ETHERNET) | best-effort (Other when ambiguous) |
isDataMetered = true | nw_path_is_expensive || nw_path_is_constrained | nw_path_is_expensive || nw_path_is_constrained | !(NET_CAPABILITY_NOT_METERED || TEMPORARILY_NOT_METERED) | never (no JDK signal) |
| Status seeded synchronously | no (first emission within tens of ms) | no | yes (from activeNetwork) | no (first poll, then every interval) |
gradle/libs.versions.toml) are the single source of
truth. Web-search before bumping any dependency (CLAUDE.md §2). Kotlin
is pinned at the highest version SKIE supports — currently 2.3.20 with
SKIE 0.10.11.@ObjCName where the default Swift name is
awkward, @Throws on every suspend fun that can throw across the
boundary.internal by default; widen visibility only when needed (CLAUDE.md §3).Reachability.shared
(zero-setup singleton). For tests or explicit lifecycle, the asymmetric
platform factories (Reachability(context) / Reachability()) are also
public. No DI container is required by the library.Surfaced from shared tags and platforms — no rankings paid for.