ScrollRail is a customizable and interactive scroll indicator for UIKit. It works with UIScrollView, UITableView, and UICollectionView without method swizzling or delegate forwarding.

• Vertical and horizontal indicators
• Direct thumb dragging
• Automatic, persistent, and hidden visibility modes
• Correct handling of adjustedContentInset and overscroll
• Right-to-left layout support
• VoiceOver adjustable controls
• Restores the original system indicators when uninstalled
• Swift 6 concurrency-safe, main-actor API

• iOS 18 or later
• Swift 6 or later
• Xcode 16 or later

Add ScrollRail to your project with Swift Package Manager:

dependencies: [
    .package(
        url: "https://github.com/ClockLoveCoding/ScrollRail.git",
        from: "0.1.0"
    )
]

Then add ScrollRail to your target dependencies.

Alternatively, install ScrollRail with CocoaPods:

pod 'ScrollRail', '~> 0.1.0'

import ScrollRail
import UIKit

@MainActor
final class ListViewController: UITableViewController {
    private var scrollRailController: ScrollRailController?

    override func viewDidLoad() {
        super.viewDidLoad()

        scrollRailController = tableView.installScrollRail(
            configuration: ScrollRailConfiguration(
                axes: [.vertical],
                visibility: .automatic(delay: 1),
                thickness: 5,
                minimumThumbLength: 40,
                thumbColor: .systemBlue,
                trackColor: .systemBlue.withAlphaComponent(0.12),
                cornerStyle: .capsule,
                isInteractive: true
            )
        )
    }
}

The scroll view retains its controller while ScrollRail is installed. Keeping your own reference is optional.

tableView.scrollRailController?.updateConfiguration {
    $0.axes = .all
    $0.visibility = .always
    $0.thumbColor = .systemOrange
}

Configuration changes are applied immediately.

tableView.scrollRailController?.flash()
tableView.uninstallScrollRail()

Uninstalling removes observations and gestures, then restores the system indicator settings that existed before installation.

ScrollRail installs an overlay constrained to the scroll view's frameLayoutGuide. It observes scroll geometry with scoped NSKeyValueObservation tokens and listens to the existing pan gesture recognizer without becoming the scroll view delegate.

Thumb dragging maps the available thumb travel directly to the scroll view's exact content offset range. Geometry calculation is isolated from UIKit view state and covered by unit tests.

ScrollRail is available under the MIT License. See LICENSE for details.