Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/eygraber/compose-placeholder
https://github.com/eygraber/compose-placeholder
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/eygraber/compose-placeholder
- Owner: eygraber
- License: apache-2.0
- Created: 2023-10-23T01:41:21.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-04-22T10:54:40.000Z (7 months ago)
- Last Synced: 2024-04-22T12:03:18.836Z (7 months ago)
- Language: Kotlin
- Size: 594 KB
- Stars: 38
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: changelog_config.json
- License: LICENSE
Awesome Lists containing this project
- mobile-awesome - compose-placeholder - A Compose Multiplatform library which provides a modifier for display 'placeholder' UI while content is loading. (Multiplatform / Android samples)
- kmp-awesome - Compose-placeholder
README
# Placeholder
[![Maven Central](https://img.shields.io/maven-central/v/com.eygraber/compose-placeholder)](https://search.maven.org/search?q=g:com.eygraber+a:compose-placeholder)
A Compose multiplatform library (android, ios, jvm, and js) which provides a [modifier][modifier] for displaying 'placeholder' UI while content is loading.
In July 2023, the Accompanist project deprecated the placeholder artifact. This library was forked and published to replace it. See [the migration guide](https://github.com/eygraber/compose-placeholder/wiki/Accompanist-Migration-Guide)
More information on the UX provided by this library can be found on the Material Theming [Placeholder UI](https://material.io/design/communication/launch-screen.html#placeholder-ui) guidelines.
There are actually three versions of the library available:
* *Placeholder Foundation*: Provides the base functionality and depends on Jetpack Compose Foundation. This version requires the app to provide all of the colors to display.
* *Placeholder Material*. This uses the foundation library above, but also provides sensible default colors using your app's Material color palette.
* *Placeholder Material 3*. This uses the foundation library above, but also provides sensible default colors using your app's Material 3 color palette.> [!NOTE]
You only need to use one of the libraries, and most apps should use **Placeholder Material** or **Placeholder Material 3**. The APIs of the libraries are (mostly) equivalent with only the imports being different. Where possible we have provided equivalent code samples below.## Gradle
```gradle
repositories {
mavenCentral()
}dependencies {
// If you're using Material, use compose-placeholder-material
implementation("com.eygraber:compose-placeholder-material:1.0.8")// If you're using Material 3, use compose-placeholder-material3
implementation("com.eygraber:compose-placeholder-material3:1.0.8")// Otherwise use the foundation version
implementation("com.eygraber:compose-placeholder:1.0.8")
}
```### Library Snapshots
Snapshots of the current development version of this library are available, which track the latest commit.
```gradle
repositories {
maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots")
}dependencies {
implementation("com.eygraber:compose-placeholder:1.0.9-SNAPSHOT")
}
```## Basic usage
At the most basic usage, the modifier will draw a shape over your composable content, filled with the provided color.
![Basic Placeholder demo](https://github.com/eygraber/compose-placeholder/blob/master/docs/res/basic.jpg?raw=true)
### "Placeholder Material"
```kotlin
import com.eygraber.compose.placeholder.material.placeholderText(
text = "Content to display after content has loaded",
modifier = Modifier
.padding(16.dp)
.placeholder(visible = true)
)
```### "Placeholder Foundation"
```kotlin
import com.eygraber.compose.placeholder.placeholderText(
text = "Content to display after content has loaded",
modifier = Modifier
.padding(16.dp)
.placeholder(
visible = true,
color = Color.Gray,
// optional, defaults to RectangleShape
shape = RoundedCornerShape(4.dp),
)
)
```## Placeholder highlights
The library also provides some 'highlight' animations to entertain the user while they are waiting. There are two provided by the library, but you can also provide your own.
### Fade
![Fade Placeholder demo](https://github.com/eygraber/compose-placeholder/blob/master/docs/res/fade.gif?raw=true)
This highlight fades a color over the entire placeholder in and out.
### "Placeholder Material"
```kotlin
import com.eygraber.compose.placeholder.PlaceholderHighlight
import com.eygraber.compose.placeholder.material.placeholder
import com.eygraber.compose.placeholder.material.fadeText(
text = "Content to display after content has loaded",
modifier = Modifier
.padding(16.dp)
.placeholder(
visible = true,
highlight = PlaceholderHighlight.fade(),
)
)
```### "Placeholder Foundation"
```kotlin
import com.eygraber.compose.placeholder.PlaceholderHighlight
import com.eygraber.compose.placeholder.placeholder
import com.eygraber.compose.placeholder.fadeText(
text = "Content to display after content has loaded",
modifier = Modifier
.padding(16.dp)
.placeholder(
visible = true,
color = Color.Gray,
// optional, defaults to RectangleShape
shape = RoundedCornerShape(4.dp),
highlight = PlaceholderHighlight.fade(
highlightColor = Color.White,
),
)
)
```### Shimmer
![Shimmer Placeholder demo](https://github.com/eygraber/compose-placeholder/blob/master/docs/res/shimmer.gif?raw=true)
This displays a gradient shimmer effect which emanates from the top-start corner.
### "Placeholder Material"
```kotlin
import com.eygraber.compose.placeholder.PlaceholderHighlight
import com.eygraber.compose.placeholder.material.placeholder
import com.eygraber.compose.placeholder.material.shimmerText(
text = "Content to display after content has loaded",
modifier = Modifier
.padding(16.dp)
.placeholder(
visible = true,
highlight = PlaceholderHighlight.shimmer(),
)
)
```### "Placeholder Foundation"
```kotlin
import com.eygraber.compose.placeholder.PlaceholderHighlight
import com.eygraber.compose.placeholder.placeholder
import com.eygraber.compose.placeholder.shimmerText(
text = "Content to display after content has loaded",
modifier = Modifier
.padding(16.dp)
.placeholder(
visible = true,
color = Color.Gray,
// optional, defaults to RectangleShape
shape = RoundedCornerShape(4.dp),
highlight = PlaceholderHighlight.shimmer(
highlightColor = Color.White,
),
)
)
```## Contributions
Please contribute! We will gladly review any pull requests.
## License
```
Copyright 2021 The Android Open Source Project
Copyright 2023 Eliezer Graber
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttps://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```[modifier]: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier