FloatingX for Android: App, System, and Local Floating Windows

FloatingX host choices and target problems

FloatingX addresses the case where an Android application needs a view that is visually detached from its normal layout but still has controlled placement and movement. The library offers three host scopes described in the README: a system floating window using WindowManager and system-window permission, an application floating window that follows the Activity, and a local floating view attached to an Activity, Fragment, or ViewGroup. The Compose module adds support for Compose content, including a ViewModelStore and SavedState that the README says help preserve state across page changes.

This makes the library relevant to Android teams building a persistent control surface, a draggable assistant, a media control, or an in-app overlay that should survive navigation. The system host is for overlays that can remain visible outside the application, although it requires the platform permission. The app host avoids that permission requirement and follows Activity transitions. The local host is narrower, because it lives inside a specific host container rather than across the whole device or application.

The choice is therefore not simply between floating and non-floating views. It is between lifecycle scope and permission scope. A screen-local control should normally use the scope module, while a control that must follow the application across pages needs the app module. A control that remains outside the app needs the system module and an operational permission flow. FloatingX does not remove Android's permission model. It supplies different hosting paths and, according to the README, can automatically request or manually request the system permission and fall back to an app-level floating window when permission is denied.

Module selection, installation, and first app-level control

The README publishes version 3.0.0 artifacts on Maven Central through the io.github.petterpx namespace. Modules are split by capability, and the documentation says that core is brought in automatically when another module is selected. The library declares its minimum SDK as 21, while the Compose module requires API 23. Permissions and providers are declared inside the library, according to the README.

Start with the app-level artifact when the floating control should follow Activity changes but should not depend on a system permission:

dependencies {
    implementation "io.github.petterpx:floatingx-app:3.0.0"
}

The installation tutorial for a complete application is documented in the repository's quick-start and Wiki pages. The README also provides a first Kotlin configuration that creates a control named "music", loads a layout, anchors it near the center end, defines margins, enables edge adsorption with partial hiding, persists its position through FxSpStorage, enables logs, and configures an app host with a blacklist.

val control = FloatingX.install("music") {
    layout(R.layout.fx_card)
    anchor(FxGravity.CENTER_END, dy = 120f)
    margin(top = 24f, bottom = 24f)
    adsorb(FxAdsorb.Edges(setOf(FxEdge.START, FxEdge.END), halfHide = FxHalfHide(0.3f)))
    persist(FxSpStorage(app))
    enableLog("Fx-demo")
    appHost(app) {
        blacklist(SplashActivity::class.java)
    }
}
control.show()

The control is registered with the tag "music", and `control.show()` requests that it be displayed. The repository's demo can be installed through its Gradle wrapper, but that command is for the example application rather than a published setup command for every host:

./gradlew app:installDebug

The README does not specify what device output to expect from this command beyond installing the demo, so the first verification point is whether the demo page appears on the connected Android device.

Positioning, movement, and Android host lifecycle

The documented configuration model is builder-based. `layout` selects the view resource, `anchor` establishes a gravity and vertical offset, `margin` defines spacing from configured edges, and `adsorb` describes edge behavior. The example uses `FxAdsorb.Edges` with `FxEdge.START` and `FxEdge.END`, plus `FxHalfHide(0.3f)`. This configuration indicates that the floating view can attach to either horizontal edge and can partially hide. It is more precise than a generic draggable-overlay description because the placement rules are expressed as FloatingX configuration objects.

The README lists additional movement features such as draggable regions, long-press dragging, conflict handling with list scrolling, custom show and hide animations, boundary settings, and clipping behavior. It also documents anchor positioning for rotation and content-size changes, historical position saving and restoration by tag and screen orientation, and position repair after windowing or split-screen changes. These behaviors address a difficult Android issue: a floating view can be dragged correctly once, then move incorrectly after the host is recreated or its dimensions change.

Lifecycle handling is another differentiator. The library says that the floating view can avoid reconstruction when pages change, while its position, state, and animation follow the Activity. For Compose, it exposes `stateFlow` and `positionFlow` according to the Wiki summary. A blacklist or whitelist can prevent the floating view from appearing on selected pages. The app host matches classes with `isInstance`, so registering a base class also matches subclasses according to the README.

These claims describe intended mechanisms, not a guarantee that every Android OEM window configuration behaves identically. The repository includes an issue coverage matrix and configuration documentation, but the README does not claim universal support for every device, orientation, keyboard, or split-screen scenario.

System-window permission and local scope trade-offs

The system module uses WindowManager and requires the relevant Android system-floating-window permission. The README states that FloatingX can request that permission automatically or manually, and that a denied request can automatically degrade to an app-level floating window. This is a useful fallback for applications that can offer a reduced scope rather than failing outright, but it changes the product behavior: a view that was expected to remain outside the application may disappear when the app leaves the foreground.

The system host also needs application-level design around service lifecycle, LayoutParams, keyboard behavior, and permission state. The README points to a dedicated system-floating-window Wiki page for those topics, but the excerpt does not specify the exact permission key, service declaration, or fallback callback. Those details should be taken from the system module documentation rather than inferred from the app-level example.

The scope module is different. It attaches the floating view to an Activity, Fragment, or ViewGroup, which keeps it within a defined container and avoids requiring a device-wide overlay. That makes it a better fit for a help button, compact editor control, or contextual action associated with a particular screen. The trade-off is reduced reach. The local view cannot provide the same outside-app presence as a WindowManager overlay.

Compose support is split into `floatingx-compose`, with a separate minimum API of 23. A project that only needs traditional Android views should not add that module. The README also says that 3.0 is a complete rewrite with module separation and an API incompatible with 2.x. Existing integrations should inspect `docs/MIGRATION.md` and the Wiki migration page before changing dependency versions.

Alternative approaches and maintenance implications

A real alternative is to implement the overlay directly with Android's WindowManager, a custom ViewGroup, or an existing floating-view library. The direct WindowManager approach gives the application explicit control over the service, LayoutParams, touch handling, permission request, and lifecycle. The cost is that the application must implement edge measurement, rotation handling, persistence, drag conflicts, and state recovery itself. FloatingX packages those concerns behind a Kotlin DSL and Java-friendly Builder, but it also introduces its own host and configuration model.

For a screen-local overlay, a custom ViewGroup may be simpler when the application already owns the full view hierarchy. It avoids a separate floating-window abstraction and does not need system-window permission. It will not provide the app-following or outside-application behavior described by FloatingX. The choice depends on required scope, not on a general claim that one Android library is preferable.

Maintenance information is limited to repository facts. FloatingX uses the MIT license, so the repository permits use under that license subject to its terms. The last recorded push was on 2026-10-10, and the repository is not archived. The listed releases include 3.0.0 on 2026-08-30 and 2.3.7 on 2025-08-24. The project also maintains migration documentation, a Wiki, a demo module, issue coverage material, and separate modules. The README does not state a support commitment, response time, long-term compatibility promise, or release policy. The main upgrade cost visible in the repository is code adaptation from 2.x to the rewritten 3.0 API, plus checking whether the application depends on behavior or configuration that changed.

README limits for operational evaluation

The README gives a useful feature inventory and a minimal app-level example, but it does not provide performance measurements, memory behavior, device compatibility claims, or a complete rollback procedure. It also does not enumerate every system permission configuration in the excerpt. An engineer evaluating FloatingX should therefore distinguish documented capabilities from application-specific validation. The demo and linked issue coverage matrix are references for inspection, not proof of compatibility with every target device.

The most important boundary is behavioral. FloatingX can keep state through page changes according to its documentation, yet an application still has to decide which Activity, Fragment, ViewGroup, or system window owns the control. The library can fall back when system permission is denied, but the fallback cannot preserve the outside-app requirement. It can persist position by tag and screen orientation, but storage semantics and key collision behavior still belong in the application's design review.

The second boundary is migration. Because 3.0 is incompatible with 2.x, an existing application should inspect `docs/MIGRATION.md`, the linked Wiki migration page, and the API reference before replacing dependencies. A smoke test should cover the selected host, denied permission behavior, rotation, split-screen transitions, page blacklisting, drag versus list scrolling, and restoration after process recreation where supported by the application architecture.

Editorial conclusion

Adopt FloatingX when the app needs a configurable floating view whose position and state must follow Android host lifecycles, or when a system window with explicit permission handling is required. Do not choose it for a 2.x integration without planning a migration, because version 3.0 changes the API. Verify first whether the required host type, permissions, Compose support, persistence mechanism, and upgrade path fit the application. The repository was not archived, and the last push was on 2026-10-10.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Petterpx/FloatingX on GitHub
4. README
5. Releases