SKILL.md
ProgressiveBlurHeader SwiftUI Skill
Skill by ara.so — Daily 2026 Skills collection.
A drop-in SwiftUI package for sticky headers with progressive (variable-radius) blur — replicating the Apple Music, Photos, and App Store style where content scrolls underneath the header with increasing blur and tint. No clipping, no hard edges.
Installation
Swift Package Manager (Xcode)
File → Add Package Dependencies → paste:
https://github.com/dominikmartn/ProgressiveBlurHeaderSelect branch: main
Package.swift
dependencies: [
.package(url: "https://github.com/dominikmartn/ProgressiveBlurHeader", branch: "main"),
]Then add to your target:
.target(
name: "YourApp",
dependencies: ["ProgressiveBlurHeader"]
)Requirements: iOS 16+, Swift 5.9+
Core API
StickyBlurHeader
The primary component. Takes two ViewBuilder closures: header and content.
StickyBlurHeader(
maxBlurRadius: Double, // Default: 5
fadeExtension: CGFloat, // Default: 64
tintOpacityTop: Double, // Default: 0.7
tintOpacityMiddle: Double // Default: 0.5
) {
// header view (NO opaque background)
} content: {
// scrollable content
}Parameters
Parameter
Type
Default
Description
maxBlurRadius
Double
5
Max blur at the top edge. 5 = subtle, 10 = moderate, 20 = strong
fadeExtension
CGFloat
64
Points below the header the blur extends
tintOpacityTop
Double
0.7
Tint behind Dynamic Island / status bar
tintOpacityMiddle
Double
0.5
Tint at the header's vertical center
The tint color adapts automatically to light/dark mode.
Basic Usage
import SwiftUI
import ProgressiveBlurHeader
struct ContentView: View {
let items = (1...50).map { "Item \($0)" }
var body: some View {
StickyBlurHeader {
// Header — NO opaque background
HStack {
Button("Back") { }
Spacer()
Text("Library").font(.headline)
Spacer()
Button("Settings") { }
}
.padding()
} content: {
ForEach(items, id: \.self) { item in
Text(item)
.frame(maxWidth: .infinity, alignment: .leading)
.padding()
.background(Color(.secondarySystemBackground))
.cornerRadius(8)
.padding(.horizontal)
}
}
.background(Color(.systemBackground))
}
}Common Patterns
Navigation-Style Header with Back Button
import SwiftUI
import ProgressiveBlurHeader
struct AlbumDetailView: View {
let albumTitle: String
@Environment(\.dismiss) private var dismiss
var body: some View {
StickyBlurHeader(
maxBlurRadius: 8,
fadeExtension: 80,
tintOpacityTop: 0.75,
tintOpacityMiddle: 0.55
) {
HStack {
Button {
dismiss()
} label: {
Image(systemName: "chevron.left")
.fontWeight(.semibold)
}
Spacer()
Text(albumTitle)
.font(.headline)
.lineLimit(1)
Spacer()
Button {
// action
} label: {
Image(systemName: "ellipsis.circle")
}
}
.padding(.horizontal)
.padding(.vertical, 12)
} content: {
LazyVStack(spacing: 0) {
ForEach(0..<30) { index in
SongRow(index: index)
Divider().padding(.leading)
}
}
}
.background(Color(.systemBackground))
}
}Subtle Blur (Apple Photos Style)
StickyBlurHeader(
maxBlurRadius: 5,
fadeExtension: 56,
tintOpacityTop: 0.6,
tintOpacityMiddle: 0.4
) {
HStack {
Text("Photos")
.font(.largeTitle)
.fontWeight(.bold)
Spacer()
Button {
// action
} label: {
Image(systemName: "plus")
}
}
.padding(.horizontal)
.padding(.top, 8)
.padding(.bottom, 12)
} content: {
LazyVGrid(columns: [GridItem(.adaptive(minimum: 100))], spacing: 2) {
ForEach(photos) { photo in
PhotoThumbnail(photo: photo)
}
}
.padding(2)
}
.background(Color(.systemBackground))Strong Blur (App Store Style)
StickyBlurHeader(
maxBlurRadius: 12,
fadeExtension: 72,
tintOpacityTop: 0.85,
tintOpacityMiddle: 0.6
) {
VStack(spacing: 4) {
HStack {
Text("Today")
.font(.largeTitle)
.fontWeight(.bold)
Spacer()
Button {
// profile action
} label: {
Image(systemName: "person.crop.circle.fill")
.font(.title2)
}
}
HStack {
Text(Date(), style: .date)
.font(.subheadline)
.foregroundStyle(.secondary)
.textCase(.uppercase)
Spacer()
}
}
.padding(.horizontal)
.padding(.vertical, 12)
} content: {
LazyVStack(spacing: 16) {
ForEach(featuredApps) { app in
AppCard(app: app)
}
}
.padding()
}
.background(Color(.systemBackground))Dynamic Header (Height Changes)
Header height is measured automatically via GeometryReader + PreferenceKey — no manual sizing needed:
StickyBlurHeader {
VStack(alignment: .leading, spacing: 4) {
Text("Title").font(.headline)
if showsSubtitle {
Text("Subtitle").font(.subheadline).foregroundStyle(.secondary)
}
}
.padding()
// Header auto-adjusts when showsSubtitle toggles
} content: {
contentList
}
.background(Color(.systemBackground))Architecture
The component uses a three-layer ZStack:
Layer
Component
Purpose
Back
ScrollView
Content scrolls freely, never clipped
Middle
VariableBlurView + gradient
Progressive blur + adaptive tint
Front
Your header view
Floats above blur, transparent background
The blur engine is VariableBlur by nikstar, which uses the same private API Apple uses internally. It is App Store approved.
Critical Rules
❌ Never add an opaque background to the header
// WRONG — hides the blur effect
StickyBlurHeader {
Text("Header")
.background(Color.white) // ❌ Breaks the blur
}
// CORRECT — no background on header views
StickyBlurHeader {
Text("Header") // ✅ Transparent, blur shows through
}❌ Never clip the content hierarchy
// WRONG
StickyBlurHeader { ... } content: {
VStack { ... }
.clipped() // ❌ Content becomes invisible under header
}
// CORRECT — let content remain visible under blur
StickyBlurHeader { ... } content: {
VStack { ... } // ✅ No clipping
}✅ Always set a background on the outer container
StickyBlurHeader { ... } content: { ... }
.background(Color(.systemBackground)) // ✅ Required for tint to work correctlyTroubleshooting
Blur not visible / header looks opaque
- Remove any
.background(...)modifier from your header view
- Ensure no parent view adds a background before
StickyBlurHeader
Content disappears under header
- Remove any
.clipped()from the content or its ancestors
- Do not wrap content in a
ScrollView—StickyBlurHeaderprovides its own
Header height is wrong
- Do not set explicit heights on the header; let it size naturally
GeometryReadermeasures the header automatically
Tint color looks wrong in dark mode
- The tint adapts automatically; ensure
.background(Color(.systemBackground))is set on the outer view so the adaptive color has a reference
Build error: "No such module 'ProgressiveBlurHeader'"
- Confirm the package is added in Xcode under Package Dependencies
- Clean build folder: Product → Clean Build Folder (⇧⌘K)
- Check the target membership of the package in your app target
iOS version compatibility
- Minimum deployment target must be iOS 16.0 or higher
- Set in Xcode: Target → General → Minimum Deployments
iOS 26 Comparison
iOS 26 adds .safeAreaBar(edge: .top) — a native one-liner for sticky blur bars. Use ProgressiveBlurHeader when you need:
- Custom blur radius
- Adjustable tint intensity
- Extended fade below the header
- iOS 16–25 support