Skip to main content

Released documentation snapshot. This immutable manual describes viewcompose-widget-core:0.1.0-alpha02 from source revision 963e114e. For current guidance, open the current module catalog.

Widget Core

viewcompose-widget-core is the Android-facing declarative UI layer of ViewCompose. It provides the UiTreeBuilder DSL, themed component defaults, composition locals and environment propagation, composition-scoped effects and saveable state, lazy-container scopes, overlay declarations, and the render-session protocol that connects a declarative tree to an installed Android renderer.

Use it directly when authoring reusable ViewCompose components, custom hosts, theme integrations, or overlay backends. Android applications normally receive it through viewcompose-host-android, which installs the renderer, scheduling runtime, lifecycle, and saved-state boundaries.

This module does not implement View reconciliation, own Activity or Fragment lifecycle, present platform dialogs and popups, load remote images, or provide optional animation, gesture, graphics, shadow, navigation, or ConstraintLayout features. Those responsibilities remain in their dedicated modules.

Artifact and stability​

dependencies {
    implementation("com.viewcompose:viewcompose-widget-core:0.1.0-alpha01")
}
  • Stability: Alpha. Source and binary compatibility may change between alpha releases.
  • Platform: Android library, minSdk 24, compileSdk 36, and Java 11 bytecode.
  • Direct ViewCompose dependencies: viewcompose-text-core as an API dependency, with viewcompose-runtime and viewcompose-ui-contract as implementation dependencies.
  • Android runtime dependencies: AndroidX Core, AppCompat, Material Components, and Kotlin coroutines. A concrete host may expose additional dependencies.
  • Build baseline for this release: Kotlin 2.0.21 and Android Gradle Plugin 8.7.3.

Minimal component usage​

fun UiTreeBuilder.ProfileSummary(name: String, role: String) {
    UiTheme {
        Column(spacing = 8.dp) {
            Text(name, style = TextDefaults.titleMediumStyle())
            Text(role, color = TextDefaults.secondaryColor())
        }
    }
}

UiTreeBuilder records immutable VNodes. UiTheme resolves a complete token snapshot and every emitted node captures the active theme, density, locale, layout direction, and other locals needed by a later renderer or child render session.

Principal APIs​

  • UiTreeBuilder and its component functions build declarative node trees without creating Android Views.
  • Theme and UiTheme expose immutable color, typography, shape, sizing, and overlay tokens with explicit Android-theme resolution and refresh behavior.
  • UiEnvironment and the local-provider APIs scope density, locales, layout direction, content color, text style, image loading, focus, frame clock, and host capabilities.
  • remember, produceState, and effects integrate the platform-neutral composition runtime with structured coroutines and committed side effects.
  • rememberSaveable and SaveableStateRegistry preserve state through composition disposal and host recreation with transactional restoration.
  • RenderSession coordinates composition, renderer reconciliation, native commit effects, overlays, diagnostics, failure recovery, and disposal for one Android ViewGroup.
  • Overlay specifications and hosts define platform-neutral dialog, popup, bottom-sheet, snackbar, and toast identity, placement, queueing, update, and dismissal contracts.

The complete generated reference is available under the viewcompose-widget-core API tree. Because the current line is alpha, the documentation site intentionally does not expose a stable latest alias.

State, rendering, and lifecycle rules​

  • A UiTreeBuilder is an ephemeral recorder. Do not retain it or invoke a captured builder after its content block returns. Retain state and stable keys instead.
  • remember and effects require an active composition. Positional identity follows the structural call path; use stable key groups and lazy-item keys when content can move.
  • rememberSaveable registers providers only after composition commit. A failed or abandoned composition releases its restored claim so a later attempt can still restore the value.
  • UiTheme accepts at most one source: explicit tokens, an Android context, or a resolved Android theme. Android-backed providers observe configuration changes while mounted; runtime style mutations require AndroidThemeRefreshController.refresh() on the main thread.
  • Each RenderSession exclusively owns one container, its mounted nodes, composition, coroutine scope, and session-scoped overlays. Call dispose with the host lifecycle; the session cannot be reused afterward.
  • Composition preparation and tree-render failures preserve the previous frame. Failures after a renderer has established the new native tree are reported as committed-frame failures and cannot roll that tree back.
  • Overlay requests are declarative and scoped by render-session id plus request key. Omitting a previously committed request dismisses it. Platform presentation requires viewcompose-overlay-android or a custom OverlayHost.
  • Lazy collection keys must remain stable and unique. Reuse, prefetch, and motion policies are renderer hints; they must not be used as business state.

Building a VNode tree is thread-confined to its active composition context. Standard Android hosts serialize rendering, state callbacks, effects, and platform operations on the main thread. Custom hosts must preserve the same ordering and ownership guarantees.

Compatibility notes​

The 0.1.0-alpha01 line establishes the first public widget, theme, local, saveable-state, overlay, and render-session contracts. Do not persist automatic saveable keys, session identifiers, VNode implementation names, callback instances, tooling metadata, or diagnostics shapes as external long-lived data. Custom renderers and hosts must be upgraded with contract changes even when an application's component source still compiles.