WearOS Scrollbar #

A Flutter plugin that implements an elegant, expressive scroll indicator for Wear OS devices, following the Material 3 Expressive design guidelines for Wear OS 6.

This package provides a customizable circular scrollbar that automatically responds to physical rotary input (such as a rotating bezel or crown) and provides haptic feedback, making your Wear OS applications feel truly native and premium.

✨ Features #

Material 3 Expressive Design: Modern, sleek circular scrollbar tailored specifically for round screens, with support for the dynamic fisheye scaling effect via WearOsExpressiveItem.
Smooth Rotary Input & Natural Decay: Automatically listens to the watch's physical rotary encoder (crown/bezel) and scrolls with continuous exponential decay physics matching Wear OS system settings.
Native Wear OS Rotary Haptics: Official Android ROTARY_SCROLL_TICK crown detents and ROTARY_SCROLL_LIMIT boundary clicks for Pixel Watch 3 and modern Wear OS devices.
Touch Interruption: Fluidly cancels active rotary deceleration whenever the user touches the screen to perform a manual drag.
Highly Customizable: Easily configure scroll velocity (rotarySensitivity), smooth scrolling, colors, stroke width, margins, and span angle.
Hide Indicator: Option to hide the visual indicator while keeping rotary and haptic functionality.
Auto-hiding: Smoothly fades out when not actively scrolling.

📸 Example App #


Initial View	Scrolling Down	Reaching Bottom

🛠 Installation #

Add the dependency to your pubspec.yaml:

dependencies:
  wear_os_scrollbar: ^1.0.0

⚙️ Configuration #

Ensure your android/app/build.gradle is configured correctly for Wear OS:

android {
    defaultConfig {
        minSdkVersion 26 // Or your current minSdk, ideally 26+ for modern Android/WearOS features
    }
}

To make the app assume the rounded canvas appearance on rounded screens, you can add this to your MainActivity.kt:

import android.os.Bundle
import io.flutter.embedding.android.FlutterActivity

class MainActivity : FlutterActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        intent.putExtra("background_mode", "transparent")
        super.onCreate(savedInstanceState)
    }
}

🚀 Usage #

Wrap your scrollable content (like a ListView or SingleChildScrollView) with the WearOsScrollbar widget. You can also wrap individual items in WearOsExpressiveItem for Material 3 Expressive scaling.

Important: You must provide the exact same ScrollController to both the WearOsScrollbar and your scrollable child.

import 'package:material_ui/material_ui.dart';
import 'package:wear_os_scrollbar/wear_os_scrollbar.dart';

class MyWearOsScreen extends StatefulWidget {
  const MyWearOsScreen({super.key});

  @override
  State<MyWearOsScreen> createState() => _MyWearOsScreenState();
}

class _MyWearOsScreenState extends State<MyWearOsScreen> {
  final ScrollController _controller = ScrollController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.black,
      body: WearOsScrollbar(
        controller: _controller,
        // Optional customizations (default values calibrated for native Wear OS):
        hapticFeedback: WearOsHapticFeedback.rotaryTick,
        rotarySensitivity: 0.4,
        enableSmoothScroll: true,
        enableLimitHaptic: true,
        child: ListView.builder(
          controller: _controller, // MUST be the same controller
          itemCount: 50,
          itemBuilder: (context, index) {
            return WearOsExpressiveItem(
              scrollController: _controller,
              child: ListTile(
                title: Text('Item $index'),
              ),
            );
          },
        ),
      ),
    );
  }
}

📱 Using with PageView #

WearOsScrollbar also works perfectly with PageView. If you want to use the rotary input to navigate between pages but prefer to show your own custom page indicator (like dots or a curved indicator), you can set hideIndicator: true.

WearOsScrollbar(
  controller: _pageController,
  hideIndicator: true, // Hides the default scrollbar but keeps rotary input working
  child: PageView(
    controller: _pageController,
    scrollDirection: Axis.vertical, // Works best for vertical PageView on Wear OS
    children: [
      PageOne(),
      PageTwo(),
      PageThree(),
    ],
  ),
)