SwiftUI Circular Control

A cross-platform, highly customizable circular progress control for SwiftUI.

Features

• Use as an editable control or a progress indicator
• Rich customization options with built-in and custom styles
• Built-in animation and transition support

Installation

Swift Package Manager

To install through Xcode:

1. File > Add Package Dependencies
2. Add https://github.com/philptr/PZCircularControl.git and select version 1.1.0 or later.

Or add the dependency to your Package.swift:

dependencies: [
    .package(url: "https://github.com/philptr/PZCircularControl.git", from: "1.1.0")
]

Quick Start

Static Progress

You can add a simple yet customizable progress indicator to your view in a single line of code.

// Basic usage:
CircularControl(progress: 0.4)

// Customized style:
CircularControl(
    progress: 0.75,
    strokeWidth: 15,
    style: .init(
        track: Color.secondary.opacity(0.25),
        progress: LinearGradient(
            colors: [.teal, .mint],
            startPoint: .topLeading,
            endPoint: .bottomTrailing
        )
    )
)

Interactive Control

import SwiftUI
import PZCircularControl

struct ContentView: View {
    @State private var progress = 0.7
    
    var body: some View {
        // A basic interactive control usage with the default style:
        CircularControl(progress: $progress)
        
        // A customized interactive control with a custom style:
        CircularControl(
            progress: $progress,
            strokeWidth: 15,
            style: .init(
                track: Color.secondary.opacity(0.2),
                progress: LinearGradient(
                    colors: [.blue, .purple],
                    startPoint: .topLeading,
                    endPoint: .bottomTrailing
                )
            )
        )
    }
}

Check out the example project for more usage examples.

Customization

Styles

PZCircularControl supports custom styles for the track, the progress bar, and the interactive knob:

let style = CircularControlStyle(
    track: Color.gray.opacity(0.2),
    progress: LinearGradient(colors: [.blue, .purple], startPoint: .top, endPoint: .bottom),
    knob: Color.white
)

CircularControl(progress: progress, style: style)

Custom Labels

You can provide any SwiftUI view as a label:

CircularControl(progress: progress) {
    VStack {
        Image(systemName: "star.fill")
        Text(progress, format: .percent)
    }
}

A custom label can read @Environment(\.circularControlProgress) to follow the control’s current value, including edits made without a binding.

Environment Configuration

Configure behavior through environment values:

CircularControl(progress: $progress)
    // Enable continuous wrapping (off by default).
    .circularControlAllowsWrapping(true)
    // Adjust the scale of the interactive knob.
    .circularControlKnobScale(2.0)

Progress Updates

You don't have to use the Binding-based initializer to support user interaction. Instead, you may provide an initial value, specify the isEditable parameter, and track changes via a closure.

CircularControl(
    progress: progress,
    isEditable: true
) { newValue in
    print("Progress updated to \(newValue).")
}

License

MIT License

Copyright (c) 2019-2024 Phil Zakharchenko

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.