Feedback/DSProgressRing

DSProgressRing

feedback

since v1.2

Generic circular progress ring with gradient support and customizable center content. Foundation for app-specific progress indicators.

iOS 17+macOS 14+

Purpose

Display progress, completion rates, or metrics in a circular format with optional custom center content and gradient styling.

Interactive Reference

Live showroom

Need the full visual surface?

Screenshots do not scale well across every component, state, and variant. For the real interactive reference, import the package and launch DSShowcaseRoot().

Best for exploring:

variants, states, categories, and real app examples in one place.

Props

Prop	Type	Default	Description
valuereq	Double	—	Current progress value
totalreq	Double	—	Maximum value (for percentage calculation)
gradient	LinearGradient?	nil	Optional gradient for the ring (overrides color)
color	Color?	DSColor.primary	Solid color for the ring (used if gradient is nil)
lineWidth	CGFloat	12	Thickness of the ring stroke
size	CGFloat	120	Diameter of the ring
showPercentage	Bool	true	Display percentage text in center
centerContent	AnyView?	nil	Custom view to display in the center (overrides percentage)

Examples

Basic progress with gradient

Simple progress ring with category gradient.

swift

DSProgressRing(
    value: 75,
    total: 100,
    gradient: DSColor.Category.category1.gradient,
    size: 140,
    lineWidth: 14
)

Custom center content

Ring with custom icon and text in center.

swift

DSProgressRing(
    value: workoutMinutes,
    total: goalMinutes,
    gradient: DSColor.Category.category2.gradient,
    showPercentage: false,
    centerContent: AnyView(
        VStack(spacing: 4) {
            Image(systemName: "flame.fill")
                .font(.system(size: 32))
                .foregroundStyle(DSColor.Category.category2.gradient)
            Text("\(Int(workoutMinutes)) min")
                .dsTextStyle(.bodyMd)
        }
    )
)

With label wrapper

Use DSProgressRingWithLabel for ring with title and subtitle.

swift

DSProgressRingWithLabel(
    value: 850,
    total: 1000,
    gradient: DSColor.Category.category3.gradient,
    title: "Daily Steps",
    subtitle: "850 / 1,000"
)

When to Use

✓ Use DSProgressRing for:

• Progress indicators with custom branding or gradients
• Metric displays that need custom center content (icons, multi-line text)
• Foundation for app-specific progress rings (workout, timer, goals)
• Dashboard widgets showing completion rates

✗ Avoid using for:

• Simple linear progress (use DSProgressBar)
• Loading states without specific progress (use DSSpinner)

Consider instead:

DSProgressBar

For linear progress indicators

DSCircularProgress

For simpler circular progress without gradients

Accessibility

VoiceOver

Announces 'Progress, [percentage]%, [title if present]'

Keyboard

Dynamic Type

✓ Supported

Contrast

WCAG AA compliant with gradient contrast ratios

Traits

.updatesFrequently for animated progress

Related Components

CircularProgress ProgressBar