StateLayout

StateLayout is a small Android View container that displays one of four mutually exclusive states: content, empty, error, or loading. It is intended for projects that use Android XML layouts and the classic View system.

Maintenance status: maintained. Version 1.1.0 is available from GitHub Releases. Maven Central publication is still pending; the historical 1.0.3 Bintray/JCenter artifact should not be used for new builds.

Why StateLayout?

• One predictable container for four common UI states.
• Configure views in XML or supply them programmatically.
• Preserve the selected state across Android view recreation.
• Java API that is straightforward to call from both Java and Kotlin.
• No runtime dependency on AppCompat or a networking/state-management framework.

Requirements

Component	Requirement
Library runtime	Android API 8+
Build from source	JDK 17 and Android SDK Platform 36
Sample target	Android API 36

Installation

GitHub Release

Download statelayout-1.1.0.aar from the v1.1.0 release, place it in your app's libs directory, and add:

dependencies {
    implementation files('libs/statelayout-1.1.0.aar')
}

You can also include this repository as source and depend on its library module:

dependencies {
    implementation project(':statelayout')
}

The planned Maven Central coordinate is io.github.wangyuyan666:statelayout:1.1.0. Do not use that coordinate until this README links to a verified Maven Central artifact. See the release procedure for the remaining Central Portal work.

XML configuration

Assign the state views and initial state directly from XML:

<com.objectlife.statelayout.StateLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/state_layout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:sl_contentView="@id/content"
    app:sl_emptyView="@id/empty"
    app:sl_errorView="@id/error"
    app:sl_loadingView="@id/loading"
    app:sl_initialState="loading">

    <include android:id="@+id/content" layout="@layout/view_content" />
    <include android:id="@+id/empty" layout="@layout/view_empty" />
    <include android:id="@+id/error" layout="@layout/view_error" />
    <include android:id="@+id/loading" layout="@layout/view_loading" />
</com.objectlife.statelayout.StateLayout>

Switch state from Kotlin:

val stateLayout = findViewById<StateLayout>(R.id.state_layout)
stateLayout.setState(StateLayout.VIEW_CONTENT)

Or Java:

StateLayout stateLayout = findViewById(R.id.state_layout);
stateLayout.setState(StateLayout.VIEW_ERROR);

Programmatic configuration

Views with no parent are added to the container automatically:

val stateLayout = findViewById<StateLayout>(R.id.state_layout)
val inflater = LayoutInflater.from(this)

stateLayout
    .setContentView(inflater.inflate(R.layout.view_content, stateLayout, false))
    .setEmptyView(inflater.inflate(R.layout.view_empty, stateLayout, false))
    .setErrorView(inflater.inflate(R.layout.view_error, stateLayout, false))
    .setLoadingView(inflater.inflate(R.layout.view_loading, stateLayout, false))
    .initWithState(StateLayout.VIEW_LOADING)

For existing descendants, the original ID-based API remains available:

stateLayout.setContentViewResId(R.id.content)
        .setEmptyViewResId(R.id.empty)
        .setErrorViewResId(R.id.error)
        .setLoadingViewResId(R.id.loading)
        .initWithState(StateLayout.VIEW_LOADING);

An invalid state or a missing ID passed through the programmatic API fails immediately with an IllegalArgumentException. Missing XML references fail during inflation with an IllegalStateException. State references declared in XML are resolved after child inflation.

Build and verify

./gradlew testDebugUnitTest lintDebug assembleDebug assembleRelease

To verify the library's AAR, sources, documentation, and POM locally:

./gradlew publishReleasePublicationToMavenLocal

Project scope

StateLayout deliberately remains a focused View-system primitive. Networking, pagination, retry policy, and application state ownership belong in higher-level application code. Compose applications generally do not need a wrapper around conditional composition; a future Compose sample may demonstrate interoperability without replacing this library's View API.

Contributing and support

• Read CONTRIBUTING.md before proposing a public API change.
• Use the issue templates for reproducible bugs and focused feature requests.
• See ROADMAP.md for planned work.
• See SECURITY.md for private vulnerability reporting.
• All participants must follow CODE_OF_CONDUCT.md.

中文简介

StateLayout 是面向 Android XML/View 项目的轻量状态容器，用于在内容、空数据、错误和加载四种界面之间切换。1.1.0 已通过 GitHub Releases 发布；Maven Central 发布仍在准备中。构建、测试、贡献和发布要求见上方文档。

License

Copyright 2016 objectlife and StateLayout contributors.

Licensed under the Apache License 2.0.