PullToRefresh

Implements Material3-based pull-to-refresh functionality with multiplatform support, offering features like customizable indicators and mouse support for seamless user experience across various devices.

#ui
#material-design
#material3
#compose-ui
#compose-multiplatform
#compose

Suggest an edit

Android JVMJVMKotlin/Native

GitHub stars1

Authorslmbotero

Open issues0

LicenseMIT License

Creation dateabout 1 year ago

Last activity11 months ago

Latest release1.0.2 (11 months ago)

GitHub repository GitHub pages Wiki page

Compose Multiplatform PullToRefresh

A simple and lightweight Compose Multiplatform library that implements Material3-based pull-to-refresh functionality for JVM, Android, and iOS platforms.

✨ Features

Material 3 Pull-to-Refresh: Built following Material 3 design principles.
Multiplatform Support: Works seamlessly across Android, iOS, and JVM.
Mouse Support for JVM: Allows pull-to-refresh using mouse click and drag.
Customizable Indicator: Easily style or replace the default refresh indicator.

📦 Installation

Add the dependency to your build.gradle.kts (or build.gradle for Groovy users):

implementation("io.github.lmbotero:pull-to-refresh:<latest-version>")

or using version catalog:

[versions]
pullToRefreshVersion = "<latest-version>"

[libraries]
pullToRefresh = { module = "io.github.lmbotero:pull-to-refresh", version.ref = "pullToRefreshVersion" }

Then add the dependency to your build.gradle.kts into the common dependencies block as follows:

commonMain.dependencies {
    implementation(libs.pullToRefresh)
}

🚀 Basic Usage

Wrap your composable content inside PullToRefreshLayout:

PullToRefreshLayout(
    refreshStateEvent =
        RefreshStateEvent(
            isRefreshing = isLoading,
            onRefresh = { /* Fetch data */ },
        ),
) {
    // Your composable content here
}

🎨 Customization

You can set your own implementation of the loading indicator by passing a custom composable into indicator parameter.

See https://developer.android.com/reference/kotlin/androidx/compose/material3/pulltorefresh/package-summary.html to see the official material3 pull-to-refresh reference and documentation.

📚 API Reference

PullToRefreshLayout

@Composable
fun PullToRefreshLayout(
    refreshStateEvent: RefreshStateEvent,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    threshold: Dp = PullToRefreshDefaults.PositionalThreshold,
    state: PullToRefreshState = rememberPullToRefreshState(),
    indicator: @Composable BoxScope.() -> Unit = {
        DefaultIndicator(
            state = state,
            isRefreshing = refreshStateEvent.isRefreshing,
        )
    },
    content: @Composable BoxScope.() -> Unit,
)

Parameter	Type	Description
`refreshStateEvent`	`RefreshStateEvent`	Represents the current update state and handles the event when it changes
`modifier`	`Modifier`	Modifier for the layout
`enabled`	`Boolean`	Whether the pull-to-refresh is enabled or not
`threshold`	`Dp`	The distance threshold for triggering the refresh event
`state`	`PullToRefreshState`	State for the pull-to-refresh
`indicator`	`@Composable BoxScope.() -> Unit`	Composable loading indicator
`content`	`@Composable BoxScope.() -> Unit`	Composable content

PullToRefreshConfig

data class RefreshStateEvent(
    val isRefreshing: Boolean,
    val onRefresh: () -> Unit,
)

Parameter	Type	Description
`isRefreshing`	`Boolean`	Whether the refresh is currently in progress or not
`onRefresh`	`() -> Unit`	Function to be executed when the refresh event is triggered

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🚀 Happy coding!

This library simplifies pull-to-refresh for Compose Multiplatform, making it easy to use and customize! 💙