repository·main·Indexed 19 days ago
https://github.com/maplibre/maplibre-composeA Compose Multiplatform wrapper for MapLibre SDKs that enables interactive map rendering across Android, iOS, Desktop, and Web. The desktop implementation utilizes a Native FFI architecture requiring Java 25 and supports Vulkan (Linux, Windows) and Metal (macOS) backends. It includes a Desktop Host SPI for custom graphics integration, a dedicated threading model for graphics contexts, and support for offline map packs.
MapLibre Compose is a Compose Multiplatform wrapper around the MapLibre SDKs. It allows developers to integrate interactive maps into Compose-based user interfaces across multiple platforms.
Supported Platforms:
maplibre-compose-material3 module provides Material 3-based UI controls for MapLibre maps. These serve as an alternative to the default map ornaments, allowing you to integrate map controls into a Material 3 design system within Compose Multiplatform applications.maplibre-compose module is the primary entry point for using MapLibre within Compose Multiplatform. It is organized into several functional packages that cover the full lifecycle of map interaction, from core rendering to advanced expression styling.MapLibre Compose currently provides support for Android and iOS.
Development is actively working towards parity for other platforms. Key upcoming features include:
Note that features like programmatic layer styling, offline management, and platform location services may vary in availability depending on the target platform and its current development status.
The library is organized into the following functional areas:
org.maplibre.compose.map for the primary map composable and its fundamental components.org.maplibre.compose.camera to manage camera positioning, movement, and utilities.org.maplibre.compose.offline to handle offline map data and caching strategies.org.maplibre.compose.layers and org.maplibre.compose.sources to declaratively add map layers and data sources to your map view.org.maplibre.compose.expressions.dsl as your primary API for creating MapLibre expressions using a Kotlin DSL.org.maplibre.compose.expressions.ast to interact with the underlying Abstract Syntax Tree.org.maplibre.compose.expressions.value to access the type system, interfaces, and enums that define expression values.The Desktop implementation uses a generic JSON style API.
Sources act as live descriptors:
Layers store ID, type, source ID, source layer, zoom range, visibility, filter, layout properties, and paint properties.
setLayerProperty, setLayerFilter, and layer move/remove APIs.To add images, convert Compose ImageBitmap pixels to tightly packed premultiplied RGBA8 and use setStyleImage. Note that ImageResizeOptions (stretch metadata) are currently a known limitation in the FFI boundary.
The desktop implementation of MapLibre for Compose Multiplatform is transitioning from a JNI-based architecture to a Native FFI (Foreign Function Interface) architecture. This rewrite requires Java 25 as the minimum runtime for desktop compilation, execution, and packaging.
Key architectural components include:
compose-glfw fixture).Location support is composed of three main functional parts that work together to track and visualize user position:
rememberDefaultLocationProvider provides GPS/position data, and rememberDefaultOrientationProvider provides sensor-based orientation data.LocationPuck: A visual component that draws the user's current position and bearing on the map.LocationTrackingEffect: A Composable effect used to subscribe to updates and optionally keep the camera in sync with the user's movement or orientation.Note on Platforms: Android and iOS include default providers. On Desktop and Web, you must supply a custom LocationProvider or OrientationProvider as the defaults will throw an error.
The LocationTrackingEffect controls how the camera rotates in response to location and orientation updates. You can choose from several bearing update modes:
| Bearing update mode | Camera behavior |
|---|---|
IGNORE | Keep the current camera bearing. |
ALWAYS_NORTH | Reset the camera to north. |
TRACK_COURSE | Rotate the camera with the user's direction of movement. |
TRACK_ORIENTATION | Rotate the camera with the device orientation. |
TRACK_AUTOMATIC | Use the more accurate course or orientation measurement. |
Note that LocationPuck(bearing = ...) only rotates the visual indicator on the map, whereas LocationTrackingEffect controls the actual camera rotation.
MapLibre Compose provides a Desktop Host SPI in org.maplibre.compose.desktop that allows applications to replace the default Skiko-based graphics integration with a custom host. This is useful for providing custom GPU contexts or render-target access (e.g., using compose-glfw).
DesktopMapHostFactory: Reports supported backend combinations and creates a host surface.DesktopMapHost: Owns host graphics objects and provides a composable drawing surface.DesktopMapFrame: Describes a renderable target (extent, scale factor, timestamp, etc.).DesktopRenderTarget: Provides backend-neutral wrappers around native handles.DesktopMapRenderer: Handles surface availability, extent changes, and frames.LocalDesktopMapHostFactory: A CompositionLocal used to provide the host factory. The default implementation is the Skiko host.By providing a custom implementation of these interfaces, you can decouple MapLibre's map behavior from the specific Compose host used.