PercentagesWithAnimationCompose - GitLite

KO | EN

gitlite — search

#git #agents #http #c #containers #swift #cli #docker #css #cpp

PercentagesWithAnimationCompose

(★ 15)

This library is designed to provide developers with an easy way to implement percentages with custom Compose views and animations, including linear, circular, circle, gradient circle and wave percentages

File Explorer

ZIP Download

- - Project_Default.xml
- .gitignore
- AndroidProjectSystem.xml
- appInsightsSettings.xml
- compiler.xml
- deploymentTargetSelector.xml
- deviceManager.xml
- gradle.xml
- kotlinc.xml
- markdown.xml
- migrations.xml
- misc.xml
- runConfigurations.xml
- vcs.xml
- .gitignore
- build.gradle.kts
- proguard-rules.pro
- - gradle-wrapper.jar
  - gradle-wrapper.properties
- libs.versions.toml
- .gitignore
- build.gradle.kts
- consumer-rules.pro
- proguard-rules.pro
- example_gif.gif
- example_gif1.gif
- example_gif2.gif
- Screenshot_20240728_152344.png
- Screenshot_20260807_195415.png
- Screenshot_20260807_195427.png
.gitignore
build.gradle.kts
gradle.properties
gradlew
gradlew.bat
jitpack.yml
LICENSE
README.md
settings.gradle.kts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

No description Visit
Linktree Visit
Static Badge Visit
X Visit
LinkedIn Visit
Medium Visit
Mastodon Visit
Bluesky Visit
Dev.to blog Visit
YouTube Visit
Static Badge Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A modern and easy-to-use Jetpack Compose library that provides beautifully animated and highly
customizable percentage indicators.
It includes linear, circular, filled circle, gradient circle, and wave-style percentage components —
all built natively for Compose with smooth animations and flexible styling options.

---

## 🌟 Features

This library offers a set of beautifully animated and highly customizable progress indicators for your Jetpack Compose apps:

*   **📊 Linear Percentage:** A classic horizontal progress bar with optional labels.
*   **⭕ Circular Percentage:** A standard circular progress indicator with customizable stroke and colors.
*   **🔵 Circle Percentage:** A filled circular progress indicator.
*   **🌈 Gradient Circle Percentage:** A circular indicator with a smooth gradient fill.
*   **🌊 Wave Percentage:** An engaging circular indicator with an animated wave effect.
*   **🎬 Customizable Animations:** Control the duration and behavior of animations.
*   **🎨 Highly Stylable:** Adjust colors, sizes, strokes, and text styles to match your app's theme.

---

## 🤔 Why Use This Library?

- **Easy Integration:** Quickly implement percentage displays with minimal setup in your Compose
  projects.
- **Multiple View Types:** Support for various percentage display styles, including linear,
  circular, and gradient circle percentages.
- **Customizable:** Highly customizable to match your app's design and user interface needs.
- **Smooth Animations:** Enjoy smooth, animated transitions for percentage changes, improving user
  experience.
- **Time-Saving:** Reduces development time by providing ready-to-use components for percentage
  representation.

---

### 🛠️ Versioning

*   **JDK Version**: `17`
*   **Target SDK**: `37`
*   **Minimum SDK**: `27`
*   **Kotlin Version**: `2.4.0`
*   **Gradle Version**: `9.3.1`
*   **Build Tool Version**: `37.0.0`

---

## !! IMPORTANT NOTE

THE BETA RELEASES MAY CONTAIN MAJOR OR MINOR CHANGES. <br />

---

## ⚙️ Basic Configuration (Gradle Dependencies)

> [!IMPORTANT]  
> Check my article with the implementation <br />
> :point_right: [PercentagesWithAnimationCompose — An Animated Percentage Indicators Library for Jetpack Compose - Medium](https://medium.com/@nicosnicolaou/percentageswithanimationcompose-an-animated-percentage-indicators-library-for-jetpack-compose-f11843ee4d87) :point_left: <br />

To get started, add the JitPack repository to your `settings.gradle.kts` file.

### Groovy

```Groovy
implementation 'com.github.NicosNicolaou16:PercentagesWithAnimationCompose:1.4.0'
```

```Groovy
allprojects {
    repositories {
        maven { url "https://jitpack.io" }
    }
}
```

### Kotlin DSL

```Kotlin
implementation("com.github.NicosNicolaou16:PercentagesWithAnimationCompose:1.4.0")
```

```Kotlin
dependencyResolutionManagement {
    //...
    repositories {
        //...
        maven { url = uri("https://jitpack.io") }
    }
}
```

### libs.versions.toml

```toml
[versions]
# other versions here...
percentagesWithAnimationComposeVersion = "1.4.0"

[libraries]
# other libraries here...
percentages-with-animation-compose = { group = "com.github.NicosNicolaou16", name = "PercentagesWithAnimationCompose", version.ref = "percentagesWithAnimationComposeVersion" }
```

```Kotlin
dependencyResolutionManagement {
    //...
    repositories {
        //...
        maven { url = uri("https://jitpack.io") }
    }
}
```

---

## 🚀 Usage

Below are examples of how to implement each of the percentage indicators available in the library.

<p align="left">
  <a title="simulator_image"><img src="screenshots/Screenshot_20260807_195415.png" height="530" width="250"></a>
  <a title="simulator_image"><img src="screenshots/Screenshot_20260807_195427.png" height="530" width="250"></a>
  <a title="simulator_image"><img src="screenshots/example_gif2.gif" height="530" width="250"></a>
</p>

### 📊 Linear Percentage

| Parameters                              | Description                                                                                                                                                          |
|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `currentPercentage`                     | The current value of the Linear progress Percentage (current value must be less than or equal to maximum value currentValue >= 0 && currentValue <= maximumValue)    |
| `maxPercentage`                         | The maximum value of the Linear progress Percentage (maximum value must be greater than or equal to current value maximumValue >= 0 && maximumValue >= currentValue) |
| `percentageAnimationDuration`           | The duration of the percentage animation, default value is 1500ms                                                                                                    |
| `heightPercentageBackground`            | The height of the background of the Linear Percentage                                                                                                                |
| `heightPercentage`                      | The height of the Linear Percentage                                                                                                                                  |
| `colorPercentageBackground`             | The color of the background of the Linear Percentage                                                                                                                 |
| `colorPercentage`                       | The color of the Linear Percentage                                                                                                                                   |
| `startTextEndPadding`                   | The padding of the start text, default value is 5                                                                                                                    |
| `endTextStartPadding`                   | The padding of the end text, default value is 5                                                                                                                      |
| `roundedCornerShapeValue`               | The rounded corner shape value, default value is 0                                                                                                                   |
| `horizontalPadding`                     | The horizontal padding left and right of the Linear Percentage, default value is 0                                                                                   |
| `startTextStyle`                        | The style of the start/lest text (Optional), default value TextStyle(color = Color.Black)                                                                            |
| `endTextStyle`                          | The style of the end/right text (Optional), default value TextStyle(color = Color.Black)                                                                             |
| `leftAndRightText`                      | The left and right text, accepted values are `LEFT_ONLY`, `RIGHT_ONLY`, `BOTH` and `NONE`, default value is `NONE`                                                   |
| `showPercentageOnLinearPercentage`      | The percentage on Linear Percentage enabled the text percent on percentage view, default value false                                                                 |
| `percentageOnLinearPercentageTextStyle` | The text style of the percentage on Linear Percentage (Optional), default value TextStyle(color = Color.Black)                                                       |

---

### ⭕ Circular Percentage

| Parameters                          | Description                                                                                                                                                   |
|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `currentPercentage`                 | The current value of the progress Percentage (current value must be less than or equal to maximum value currentValue >= 0 && currentValue <= maximumValue)    |
| `maxPercentage`                     | The maximum value of the progress Percentage (maximum value must be greater than or equal to current value maximumValue >= 0 && maximumValue >= currentValue) |
| `circularSize`                      | The size of the circular percentage, default value is 100                                                                                                     |
| `percentageAnimationDuration`       | The duration of the animation in milliseconds, default value is 1500ms                                                                                        |
| `circularPercentageBackgroundColor` | The background color of the circular percentage, default value is LightGray                                                                                   |
| `circularPercentageColor`           | The color of the circular percentage, default value is Black                                                                                                  |
| `circularStrokeBackgroundWidth`     | The width of the background stroke of the circular percentage, default value is 10                                                                            |
| `circularStrokeWidth`               | The width of the stroke of the circular percentage, default value is 10                                                                                       |
| `centerTextStyle`                   | The text style of the center of the circular percentage                                                                                                       |

---

### 🔵 Circle Percentage

| Parameters                          | Description                                                                                                                                                   |
|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `currentPercentage`                 | The current value of the progress Percentage (current value must be less than or equal to maximum value currentValue >= 0 && currentValue <= maximumValue)    |
| `maxPercentage`                     | The maximum value of the progress Percentage (maximum value must be greater than or equal to current value maximumValue >= 0 && maximumValue >= currentValue) |
| `circularSize`                      | The size of the circular percentage, default value is 100                                                                                                     |
| `percentageAnimationDuration`       | The duration of the animation in milliseconds, default value is 1500ms                                                                                        |
| `circularPercentageBackgroundColor` | The background color of the circular percentage, default value is LightGray                                                                                   |
| `circularPercentageColor`           | The color of the circular percentage, default value is Black                                                                                                  |
| `circularStrokeBackgroundWidth`     | The width of the background stroke of the circular percentage, default value is 10                                                                            |
| `centerTextStyle`                   | The text style of the center of the circular percentage                                                                                                       |

### 🌈 Gradient Circle Percentage

| Parameters                    | Description                                                                                                                                                   |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `currentPercentage`           | The current value of the progress Percentage (current value must be less than or equal to maximum value currentValue >= 0 && currentValue <= maximumValue)    |
| `maxPercentage`               | The maximum value of the progress Percentage (maximum value must be greater than or equal to current value maximumValue >= 0 && maximumValue >= currentValue) |
| `circularSize`                | The size of the circular percentage, default value is 100                                                                                                     |
| `listOfColors`                | The list of gradient colors (list of colors must not be empty)                                                                                                |
| `percentageAnimationDuration` | The duration of the animation, default value is 1500ms                                                                                                        |
| `centerTextStyle`             | The text style of the center text                                                                                                                             |

---

### 🌊 Wave Percentage

| Parameters                        | Description                                                                                                                                                |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `currentPercentage`               | The current value of the progress Percentage (current value must be less than or equal to maximum value currentValue >= 0 && currentValue <= maximumValue) |
| `maxPercentage`                   | The maximum value of the progress Percentage (maximum value must be greater than or equal to 0)                                                            |
| `circularSize`                    | The size of the wave circle percentage, default value is 100                                                                                               |
| `backgroundColor`                 | The background color of the circle, default value is White                                                                                                 |
| `waveColor`                       | The color of the wave, default value is Green                                                                                                              |
| `percentageAnimationDuration`     | The duration of the animation, default value is 1500ms                                                                                                     |
| `waveFrequency`                   | The frequency of the wave, default value is 1.5                                                                                                            |
| `waveAmplitude`                   | The amplitude of the wave, default value is 10                                                                                                             |
| `waveAnimationDuration`           | The duration of the wave animation, default value is 500ms                                                                                                 |
| `continuousWaveAnimationDuration` | The duration of the continuous wave animation, default value is 2000ms                                                                                     |
| `centerTextStyle`                 | The text style of the center text                                                                                                                          |

---

### Example

```Kotlin
package com.nicos.percentageswithanimationcomposeexample

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.*
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.rounded.Refresh
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import com.nicos.percentageswithanimationcompose.*
import com.nicos.percentageswithanimationcompose.enums.LeftAndRightText
import com.nicos.percentageswithanimationcomposeexample.ui.theme.PercentagesWithAnimationComposeTheme

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContent {
      PercentagesWithAnimationComposeTheme {
        // Use rememberSaveable to keep the state across configuration changes
        var currentTargetPercentage by rememberSaveable { mutableFloatStateOf(70F) }

Scaffold(
          modifier = Modifier.fillMaxSize(),
          containerColor = Color(0xFFFAFAFA), // Very subtle off-white for a clean look
          floatingActionButton = {
            FloatingActionButton(
              onClick = {
                currentTargetPercentage = (10..100).random().toFloat()
              },
              containerColor = Color(0xFF1E1E1E), // Sleek black FAB
              contentColor = Color.White,
              shape = RoundedCornerShape(16.dp)
            ) {
              Icon(Icons.Rounded.Refresh, contentDescription = "Refresh Animations")
            }
          }
        ) { innerPadding ->
          PercentagesList(
            modifier = Modifier.padding(innerPadding),
            percentage = currentTargetPercentage
          )
        }
      }
    }
  }
}

@Composable
fun PercentagesList(modifier: Modifier = Modifier, percentage: Float) {
  val scrollState = rememberScrollState()
  Column(
    modifier = modifier
      .fillMaxSize()
      .verticalScroll(scrollState)
      .padding(
        top = 40.dp,
        bottom = 100.dp,
        start = 24.dp,
        end = 24.dp
      ),
    horizontalAlignment = Alignment.CenterHorizontally
  ) {

// --- Header ---
    Text(
      text = "Animations",
      style = TextStyle(
        color = Color(0xFF121212),
        fontSize = 34.sp,
        fontWeight = FontWeight.ExtraBold,
        letterSpacing = (-1).sp
      ),
      modifier = Modifier.padding(bottom = 50.dp)
    )

// --- Linear Percentage ---
    SectionTitle("Linear Percentage")
    LinearPercentage(
      currentPercentage = percentage,
      maxPercentage = 100F,
      heightPercentageBackground = 50,
      heightPercentage = 50,
      roundedCornerShapeValue = 25,
      horizontalPadding = 0,
      colorPercentageBackground = Color(0xFFE9ECEF),
      colorPercentage = Color(0xFF3A86FF), // Vibrant Blue
      startTextStyle = TextStyle(
        color = Color(0xFF3A86FF),
        fontSize = 16.sp,
        fontWeight = FontWeight.Bold
      ),
      endTextStyle = TextStyle(
        color = Color.LightGray,
        fontSize = 16.sp,
        fontWeight = FontWeight.Bold
      ),
      leftAndRightText = LeftAndRightText.BOTH,
    )
    Spacer(modifier = Modifier.height(70.dp))

// --- Circular Percentage ---
    SectionTitle("Circular Percentage")
    CircularPercentage(
      currentPercentage = percentage,
      maxPercentage = 100F,
      centerTextStyle = TextStyle(
        color = Color(0xFFFF006E), // Vibrant Pink
        fontSize = 24.sp,
        fontWeight = FontWeight.Bold
      ),
    )
    Spacer(modifier = Modifier.height(70.dp))

// --- Circle Percentage ---
    SectionTitle("Circle Percentage")
    CirclePercentage(
      currentPercentage = percentage,
      maxPercentage = 100F,
      centerTextStyle = TextStyle(
        color = Color(0xFF8338EC), // Deep Purple
        fontSize = 24.sp,
        fontWeight = FontWeight.Bold
      ),
    )
    Spacer(modifier = Modifier.height(70.dp))

// --- Gradient Circle Percentage ---
    SectionTitle("Gradient Circle")
    GradientCirclePercentage(
      currentPercentage = percentage,
      maxPercentage = 100F,
      listOfColors = mutableListOf(
        Color.Green,
        (Color.Green.copy(alpha = 0.3f)),
        Color.White
      ),
      centerTextStyle = TextStyle(
        color = Color(0xFFFB5607),
        fontSize = 24.sp,
        fontWeight = FontWeight.Bold
      ),
    )
    Spacer(modifier = Modifier.height(70.dp))

// --- Wave Percentage ---
    SectionTitle("Wave Percentage")
    WavePercentage(
      currentPercentage = percentage,
      maxPercentage = 100F,
      percentageAnimationDuration = 4_000,
      centerTextStyle = TextStyle(
        color = Color(0xFF00B4D8), // Ocean Blue
        fontSize = 24.sp,
        fontWeight = FontWeight.Bold
      ),
    )
  }
}

// Reusable clean title to keep code DRY and maintain consistent beautiful typography
@Composable
fun SectionTitle(title: String) {
  Text(
    text = title,
    style = TextStyle(
      color = Color(0xFF2B2D42),
      fontSize = 20.sp,
      fontWeight = FontWeight.SemiBold,
      letterSpacing = 0.5.sp
    )
  )
  Spacer(modifier = Modifier.height(24.dp))
}
```

---

## ⭐ Stargazers

If you enjoy this project, please give it a star!
Check out all the stargazers
here: [Stargazers on GitHub](https://github.com/NicosNicolaou16/PercentagesWithAnimationCompose/stargazers)

---

## 🙏 Support & Contributions

This library is actively maintained. Feedback, bug reports, and feature requests are welcome! Please feel free to **open an issue** or submit a **pull request**.