ScrollRail

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

Features

• 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

Requirements

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

Installation

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'

Usage

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.

Update configuration

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

Configuration changes are applied immediately.

Flash or uninstall

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

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

Design

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.

License

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