GeoQibla Documentation¶

Version 0.0.1

Kotlin Multiplatform Compose Qibla direction UI for Android and iOS apps. Use the default screen when you want a complete compass flow, or subscribe to controller state when you need a custom interface.

Get Started in 60 Seconds¶

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.shahidzbi4213:geoqibla:0.0.1")
        }
    }
}

import androidx.compose.runtime.Composable
import com.shahid.tech.qibla.GeoQiblaScreen
import com.shahid.tech.qibla.rememberQiblaController

@Composable
fun QiblaRoute() {
    val controller = rememberQiblaController()
    GeoQiblaScreen(controller = controller)
}

GeoQiblaScreen starts the controller while it is in composition and stops it when it leaves composition.

Features¶

Compose-first default UI with compact and wide layouts.
Headless controller through QiblaController.state.
Location and heading state for permissions, settings, calibration, tilt, and errors.
Qibla bearing and distance calculated from the current fix.
Configurable alignment thresholds, smoothing, haptics, and callbacks.
Styling, localization, and slots for replacing visible regions.

Installation¶

Start with these pages:

Installation - dependency setup and platform requirements.
Quick Start - first working default screen.
Configuration - tune runtime behavior.
Android example and iOS example - platform copy-paste setup.

Core Concepts¶

Default Screen¶

GeoQiblaScreen renders a complete compass experience from a QiblaController. It shows state messages, action buttons, a compass dial, a target badge, and status rows.

Controller State¶

rememberQiblaController() creates a controller backed by platform location and heading services. Its state is a StateFlow<QiblaState> containing the current UI state, compass data, location data, sensor accuracy, orientation source, and optional error message.

Customization¶

Use QiblaStyle for visual tokens, QiblaStrings for copy and layout direction, and QiblaSlots for replacing default regions while keeping the controller behavior.

Platform Requirements¶

Platform	Minimum	Runtime services
Android	API 26	`LocationManager`, `SensorManager`, foreground location permission
iOS	iOS target supported by your KMP app	`CoreLocation`, heading updates, when-in-use location permission

Support¶

License¶

Apache 2.0. See License.