Swiftpack.co - Package - luispadron/UICircularProgressRing


A circular progress bar for iOS written in Swift



  • 2 views, progress or timer
  • Interface builder designable
  • Highly customizable and flexible
  • Easy to use
  • Fluid and interruptible animations
  • Written in Swift
  • RTL language support

Apps Using UICircularProgressRing


NOTE: Objective-C support: Support for Objective-C has been dropped in version 5.0.0, use version 4 or lower if you are using Objective-C.

CocoaPods (Recommended)

  1. Install CocoaPods

  2. Add this repo to your Podfile

    target 'Example' do
        # IMPORTANT: Make sure use_frameworks! is included at the top of the file
        pod 'UICircularProgressRing'
  3. Run pod install

  4. Open up the .xcworkspace that CocoaPods created

  5. Done!


Important: Interface builder support with Carthage is either broken or extremely limted

To use with Carthage

  1. Make sure Carthage is installed

    brew install carthage

  2. Add this repo to your Cartfile

    github "luispadron/UICircularProgressRing"

  3. Install dependencies carthage update --platform iOS


Interface Builder

Simply drag a UIView into your storyboard. Make sure to subclass UICircularProgressRing and that the module points to UICircularProgressRing.

Design your heart out


UICircularProgressRing Example

override func viewDidLoad() {
  // Create the view
  let progressRing = UICircularProgressRing()
  // Change any of the properties you'd like
  progressRing.maxValue = 50
  progressRing.style = .dashed(pattern: [7.0, 7.0])
  // etc ...

To set a value and animate the view

// Somewhere not in viewDidLoad (since the views have not set yet, thus cannot be animated)
// Remember to use unowned or weak self if referencing self to avoid retain cycle
progressRing.startProgress(to: 49, duration: 2.0) {
  print("Done animating!")
  // Do anything your heart desires...

// Pause at any time during a running animation

// Continue where you left off after a pause

UICircularTimerRing Example

override func viewDidLoad() {
	// create the view
	let timerRing = UICircularTimerRing()

Animate and set time

						// seconds
timerRing.startTimer(to: 60) { state in
    switch state {
    case .finished:
    case .continued(let time):
        print("continued: \(time)")
    case .paused(let time):
        print("paused: \(time)")

timerRing.pauseTimer() // pauses the timer

timerRing.continueTimer() // continues from where we paused

timerRing.resetTimer() // resets and cancels animations previously running


Please read this before creating an issue about how to use the library:



Do you use this library? Want to be featured? Go here.


Stars: 983
Help us keep the lights on


Used By

Total: 0


v6.0.2 - Mar 2, 2019

Version 6.0.2

  • Fix issue with formatter initializers being interal, they're now public as intended.

v6.0.1 - Feb 25, 2019

Version 6.0.1

  • Fix bug relating to label being removed during animation (#171)

v6.0.0 - Feb 22, 2019

Version 6.0.0

  • Fixed issue with API of UICircularRingStyle which made it impossible to have both a gradient and outer ring style, etc.
  • Refactor way that UICircularRingValueFormatter works. It's now a simple protocol which anyone can conform to. There are two concrete implementations from 5.0.0 which can still be used, however, they're now structs so cannot be mutated.

Breaking Changes

  • Due to the fact that both the .style property now doesnt allow setting .gradient, this API has been broken. Instead, use the new .gradientOptions property to set a gradient, and .style if you need extra styling on top of gradient
  • Because the value formatter are now structs, they cannot be modified with . syntax. Instead create a brand new formatter and assign to the .valueFormatter property. This will be over all much better in the future, less state and structs are cool!

v5.1.0 - Feb 8, 2019

Version 5.1.0

wow bug fixes already?

  • Fixed issue with timing function for UICircularTimerRing not being set properly
  • Rethink how the timer handler notifies about state, checkout UICircularTimerRing.State

v5.0.0 - Feb 8, 2019

Version 5.0.0

Major changes

  • New UICircularTimerRing view!
  • Complete API overhaul

New changes

  • Refactored the UICircularProgressRing class into two classes, a new base class UICircularRing and the concrete implementation UICircularProgressRing.
  • Added new UICircularTimerRing view which allows setting a timer, pausing, continuing etc. Without worrying about formatting the value string, get accurate time, etc.
  • Almost the entire code and API has been refactored
  • Add new UICircularRingValueFormatter for much nicer handling of formatting values for both views
  • Add new UICircularGradientOptions and updated UICircularRingStyle to be much more "swifty" in order to use case stored properties.
  • Removed a ton of duplicated code between layer and actual ring class, no longer using a ton of @NSManaged properties, instead the layer asks the ring for the needed values. This looks much nicer.

Bug fixes

  • Fixed issue with gradient style not having the correct radius and thus clipping
  • Fixed issues with border clipping in some cases

Breaking changes

  • Removed most Objective-C support, because being forced to write nice, new and maintainable code for both Swift and Objective-C has led to issues with adding new features, and its just not feasible if I want to be able to maintain and do cool things with this project. It sucks in terms of backwards compatibility but in the long run I think it'll be worth it.
  • Removed a ton of @IBInspectable properties, a lot of these like ringStyle behaved really badly, they required using some sort of integer and then converting that into the actual enum type for the ring style, all properties that had this issue have been removed. Until Apple adds support for enum, or more complex properties I'll only be providing IB support for the basic properties of the ring.
  • A lot of API changes were done to the styling of the ring, take a look at the docs, specifically UICircularRingStyle, UICircularGradientOptions, and UICircularRingValueFormatter.

Migrating from version 4

I expect the migration to be painful, I'm very sorry! I felt that the only way to keep this library going into the future was to completely overhaul and update the API and underlying code. This has obviously led to breaking just about everything, again, I'm sorry.

Some tips:

  • If you were using interface builder, take a look at the docs for UICircularRing and UICircularProgressRing. A lot of @IBInspectable properties have been removed/renamed. If these were set in your storyboards/xibs, they will be broken and must be removed from the views settings in IB.
  • Complex styling options are now done in code, with .style, .valueFormatter and optionally .valueKnobStyle. Take a look at the docs to learn more.