CircleProgress: Three Android Progress Views from One Small Library

What CircleProgress replaces in an Android layout

Android ships ProgressBar, and it covers horizontal and indeterminate cases well. What it does not give you out of the box is a ring that fills by degrees, a donut with a drawable or VectorDrawable sitting in its centre, or an arc with a caption underneath. CircleProgress packages exactly those three shapes as custom views so you can drop them into a layout file and set the value with an XML attribute instead of writing a custom onDraw yourself.

The audience is narrow and specific: an Android developer maintaining a Java or Kotlin app that already uses XML layouts, who needs a static indicator rather than an animated one. The README frames the origin of the project clearly, saying it was inspired by daimajia/NumberProgressBar and by CleanMaster, and the demo screenshots in the repository follow that visual style. This is not a charting library and not a general drawing toolkit. It is three views with a fixed set of attributes.

How the three views are structured

The library module sits alongside example/ and demos/ in the repository, and the published artifact exposes three classes under the package com.github.lzyzsd.circleprogress: DonutProgress, CircleProgress and ArcProgress. Each one is declared in a layout with its own attribute namespace, and each has a matching declare-styleable block in the README listing the attributes it reads.

DonutProgress is the richest of the three. Its attributes cover the finished and unfinished stroke colours and widths, the text size and colour, prefix and suffix strings, a background colour, and two extras: donut_inner_drawable, which the README says adds a drawable or VectorDrawable to the centre, and donut_show_text, which shows or hides the bottom text. CircleProgress has a smaller surface: progress, max, finished and unfinished colours, text size and colour, and prefix and suffix strings. ArcProgress adds geometry controls that the other two lack, including arc_angle as a float, arc_stroke_width, a separate suffix text size and padding, and arc_bottom_text for the caption under the arc.

The 2.0.0 change list is where the internal design becomes visible. It states that the ArcProgress busy-loop animation was replaced with a ValueAnimator, that Paint object recreation on every invalidate was fixed, that the DonutProgress RectF calculation moved from onDraw to onSizeChanged, and that duplicate attribute reads and a wrong Bundle type in DonutProgress were fixed. Those are all draw-path and state-restoration concerns, which tells you the views do their own rendering rather than wrapping ProgressBar. The same list records that CircleProgress changed its progress type from int to float, so if you are upgrading from 1.x, that is a source-level difference worth checking in your own code.

Installing CircleProgress from JitPack and drawing a first donut

The library is distributed through JitPack, not Maven Central, so the repository has to be added before the dependency resolves. The README shows the modern settings.gradle form using dependencyResolutionManagement. Add the JitPack URL to the repositories block:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

Then declare the dependency in the module that uses it. The README gives the coordinate with the v2.0.0 tag:

dependencies {
    implementation 'com.github.happydog-intj:CircleProgress:v2.0.0'
}

With the dependency in place, a donut is declared directly in XML. The README's first example sets only the progress value and lets the defaults handle the rest:

<com.github.lzyzsd.circleprogress.DonutProgress
    android:layout_marginLeft="50dp"
    android:id="@+id/donut_progress"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    custom:donut_progress="30"/>

A fuller version from the README sets the stroke widths, colours, an inner drawable and hides the text. Note that the custom namespace has to be declared on the root element of your layout, and that the README's notice applies here: always use the same width and height for progress views.

<com.github.lzyzsd.circleprogress.DonutProgress
    android:layout_marginLeft="50dp"
    android:id="@+id/donut_progress"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    custom:donut_finished_color="#0066FF"
    custom:donut_finished_stroke_width="15dp"
    custom:donut_inner_drawable="@drawable/ic_vector_star_black_48dp"
    custom:donut_show_text="false"
    custom:donut_unfinished_color="#f5f5f5"
    custom:donut_unfinished_stroke_width="15dp"/>

If you build the library from source instead, the README gives two commands, one per platform:

./gradlew assembleDebug

gradlew.bat assembleDebug

The equal width and height constraint

The README's notice is short and easy to skip: please always use same width and height for progress views. It appears before any of the view examples, which suggests it is the failure mode people hit first. A ring drawn into a non-square bounds will not be a circle, and a donut's stroke geometry does not have an obvious fallback when the two dimensions differ. The README does not explain what happens if you ignore it, and it does not document any error or warning. So the constraint is a convention you have to enforce yourself in the layout, not something the library appears to guard against.

That matters in practice because wrap_content appears in every README example, and wrap_content on a view whose measured size depends on its own drawing can produce a square only if the view's onMeasure cooperates. The README does not document the measurement behaviour, so the safe path is to give the views explicit equal dimensions like the 100dp by 100dp used in the CircleProgress and ArcProgress examples.

Where CircleProgress is the wrong tool

The library covers three static shapes. It has no documented indeterminate mode, so it cannot replace a spinner while data loads. It has no Compose composables, which is a real limitation if your app has moved its UI layer to Jetpack Compose, since the views would need an AndroidView interop wrapper. There is also no published API reference beyond the README and the attribute tables in it; the README does not document listener interfaces, programmatic setters, or how to animate a value change from code. If you need a progress indicator that animates between values on demand, the documented surface here does not tell you how to do it.

There is a version boundary worth noting too. The 2.0.0 release raised minSdk to 21 and migrated to AndroidX. If your app still uses the old support library, or supports API levels below 21, 2.0.0 is not a drop-in. The README does not describe a migration path for that case, and it does not list which 1.x version to stay on.

CircleProgress against the platform ProgressBar

The obvious alternative is Android's own ProgressBar, which is part of the framework and needs no dependency. ProgressBar gives you a horizontal bar or an indeterminate spinner, plus a style attribute and tinting on newer API levels. What it does not give you is a ring whose arc angle you control, or a donut with a VectorDrawable in the middle. ArcProgress exposes arc_angle as a float, and DonutProgress exposes donut_inner_drawable; neither has a ProgressBar equivalent without writing a custom view.

The trade-off runs the other way as well. ProgressBar is maintained with the platform, is themed by your app theme, and works with accessibility services by default. CircleProgress added accessibility support in 2.0.0 according to the change list, which is a meaningful improvement over earlier versions, but it is still a third-party view with no release notes beyond the README. If a plain horizontal bar satisfies the design, the framework view is the lower-risk choice.

Licence, maintenance and upgrade cost

The repository carries the Do What The Fuck You Want To Public License, version 2, dated December 2004, with copyright attributed to Bruce Lee. The licence text permits copying and distributing verbatim or modified copies, and permits changing the licence as long as the name is changed. That is a permissive, non-copyleft arrangement, but it is not a licence many corporate legal reviews encounter often, and the repository metadata does not list a standard SPDX identifier. Treat the licence text in the repository as the source of truth and let your own review decide, since this is not legal advice.

The last push to the repository was on 2026-09-11, so the project is not dormant. There are no retrieved releases, so the v2.0.0 tag referenced in the Gradle coordinate is the version marker to rely on, and the README's Changes section is the only changelog available. Upgrading means checking three things: that minSdk is 21 or higher, that the project is on AndroidX, and that any code reading CircleProgress progress values accounts for the int-to-float change in 2.0.0. Beyond that, the dependency is a single artifact with no transitive framework to keep in step.

Editorial conclusion

Adopt it if you need a static circular, donut or arc indicator inside an existing Android layout and you are already on AndroidX with minSdk 21 or higher; the three views are declared in XML and configured through custom: attributes. Do not adopt it if you need determinate animations with a documented API, an indeterminate spinner, or Compose support, and do not expect anything beyond what the README lists. Verify first that your minSdk is at least 21, that the JitPack coordinate com.github.happydog-intj:CircleProgress:v2.0.0 resolves in your build, and that equal layout_width and layout_height are acceptable for every instance, since the README states the views must always use the same width and height.

Frequently asked questions

Official sources

1. happydog-intj/CircleProgress on GitHub
2. Issues
3. README