# smooth_page_indicator for Animated Flutter Page Indicators

> smooth_page_indicator is a Flutter package for animated page indicators driven by a PageController or an active index. It supports several built-in effects, vertical layouts, direct color settings, and a customization path through CustomizableEffect.

**Milad-Akarie/smooth_page_indicator** — Flutter Smooth PageView indicators

- Repository: https://github.com/Milad-Akarie/smooth_page_indicator
- Stars: 1,458 · Forks: 163
- Language: Dart
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/milad-akarie-smooth-page-indicator

## Why smooth_page_indicator Exists

smooth_page_indicator addresses a focused Flutter UI problem: showing the current position in a sequence of pages while animating the change between indicators. It is intended for applications that present content through pages, such as onboarding sequences, cards, galleries, or horizontally arranged feature panels. The repository describes the package as a collection of animated indicators rather than a complete pager implementation. That boundary matters because the package does not replace the pages themselves or provide the navigation model behind them.

The main package has two entry points with different data requirements. SmoothPageIndicator follows a PageController's scroll offset, so the visual state can reflect movement through pages. AnimatedSmoothIndicator needs only an active index and handles its animation internally. This makes the package useful both for pager-backed screens and for interfaces whose selected page is already controlled by application state.

The package targets Flutter developers rather than users of a general-purpose navigation library. Its visible functionality is focused on the indicator row, including active and inactive dot colors, dimensions, spacing, axis direction, and effect-specific movement. The README does not document labels, page titles, clickable page navigation beyond the onDotClicked callback, or accessibility behavior, so those needs should not be assumed from the indicator visual itself.

## Controller and Index Data Flow in smooth_page_indicator

SmoothPageIndicator receives a PageController, an item count, and an effect. According to the README, it uses the PageController's scroll offset to animate the active dot. The page controller therefore remains the source of movement for this widget. The count tells the indicator how many positions exist, while the effect controls how the active position is drawn or moved.

The documented controller-backed form is short because the widget concentrates configuration in its constructor. Its onDotClicked callback receives the selected index. The snippet leaves the callback body empty, so it establishes the callback contract without demonstrating whether navigation is performed immediately, queued, or handled elsewhere. Developers integrating page navigation will need to connect that callback to their own page-switching logic.

AnimatedSmoothIndicator follows a different data path. It receives activeIndex instead of controller and count, then animates toward that index. This is the package's built-in alternative for cases where a PageController is unnecessary or unavailable. The README does not describe synchronization between the two widgets, so an application should select the entry point that matches its existing state model rather than treating them as interchangeable layers.

Both forms accept an effect. The documented effect choices include Worm, Expanding Dots, Jumping dot, Scrolling Dots, Slide, Scale, Swap, Color Transition, and custom demos. The effect is not cosmetic configuration added after rendering; it is part of the component's API and the documented source of its animation style.

## Installing and First Using the Package

The README does not provide an installation command or a dependency snippet. It links to the package version page on pub.dev, so the documented source for obtaining the Dart package is that listing. The repository includes a `pubspec.yaml`, but its complete SDK, Flutter, and package-version constraints are not shown in the README. Those fields should be checked before adding the dependency to an application.

For a first controller-backed use, the README supplies this widget example. The surrounding screen must already have a `PageController` named `controller`; the example does not include its declaration or a complete `PageView`, so adding undocumented setup would misrepresent the repository's instructions.

```dart
SmoothPageIndicator(    
   controller: controller,  // PageController    
   count:  6,    
   effect:  WormEffect(),  // your preferred effect    
   onDotClicked: (index){    
  }
)   
```

The reader should expect six indicator positions because `count` is `6`, with `WormEffect()` selected as the animation and an index callback exposed for dot interaction. The README does not describe behavior for `count` values below two, nor does it specify a callback side effect.

If no PageController is available, the documented alternative accepts an active index. The value represented by `yourActiveIndex` must come from the caller's state; the README does not provide a state-management example.

```dart
AnimatedSmoothIndicator(    
   activeIndex: yourActiveIndex,    
   count: 6,    
   effect: WormEffect(), 
)   
```

## Effects, Axis Direction, and Scrollable Dot Behavior

The effect list gives the package a broader visual scope than a simple row of fixed dots. Worm can use the documented thin style. Jumping dot has a variant with vertical offset, and Swap has a `SwapType.yRotation` variant. Slide, Scale, Expanding Dots, Scrolling Dots, and Color Transition cover different movement or rendering choices. The README includes GIF previews for these effects, but those files demonstrate intended appearance rather than measured animation timing.

Horizontal layout is the default in the basic examples. Setting `axisDirection` to `Axis.vertical` changes the documented layout direction:

```dart
SmoothPageIndicator(    
   controller: controller,  // PageController    
   count:  6,    
   axisDirection: Axis.vertical,    
   effect:  WormEffect(), 
)   
```

This matters for vertical page views and other layouts where a horizontal indicator would consume the wrong space or communicate the wrong orientation. The README states that both horizontal and vertical layouts are supported, but it does not specify every effect's rendering behavior under the vertical setting.

Scrolling Dots is presented separately as useful when there are many pages. That is an explicit design position in the README: the effect is intended to reduce the need to display every dot at once when the page count is large. The repository does not document a threshold for switching from a normal dot row to Scrolling Dots, nor does it provide configuration for determining when the indicator should scroll.

## Theme Colors and Effect-Level Customization

The README distinguishes inherited theme configuration from direct effect settings. Its fallback colors are `Color(0xFF3F51B5)` for `activeDotColor` and `Color(0xFF9E9E9E)` for `dotColor`. These values are package defaults, not values taken from Flutter's `ThemeData`. That distinction matters for applications expecting a Material theme color to flow automatically into the indicator. The README says to override the defaults for a descendant subtree with `SmoothPageIndicatorTheme`, or to set the two color properties directly on an effect.

The package also exposes effect-specific properties. For `SlideEffect`, the documented example sets spacing, radius, dot width, dot height, paint style, stroke width, inactive dot color, and active dot color. The values below are copied from the README:

```dart
SmoothPageIndicator(    
   controller: controller,    
   count:  6,    
   axisDirection: Axis.vertical,    
   effect:  SlideEffect(   
      spacing:  8.0,   
      radius:  4.0,   
      dotWidth:  24.0,   
      dotHeight:  16.0,   
      paintStyle:  PaintingStyle.stroke,   
      strokeWidth: 1.5,   
      dotColor:  Colors.grey,   
      activeDotColor:  Colors.indigo   
  ), 
)   
```

For more extensive customization, the README points to `CustomizableEffect`. It presents several customizable demos, but the README does not document the full property set or explain which animation primitives `CustomizableEffect` supports. The repository's example and demo directories are therefore the relevant places to inspect for concrete usage. The package should not be adopted on the assumption that every built-in effect exposes the same properties.

## Limitations, Maintenance, and the AnimatedSmoothIndicator Alternative

The package has a narrow purpose, and that narrow scope is also its main limitation. It is an indicator package, not a replacement for `PageView`, a routing system, or application-level pagination state. A screen that needs text labels, semantic descriptions, clickable page titles, or a complete navigation control would need additional code. The README does not document accessibility semantics, localization of indicator labels, animation preferences, or reduced-motion behavior. Those omissions matter for production interfaces, but the available repository documentation does not support claims that the package cannot support them.

The alternative built into the project is `AnimatedSmoothIndicator`. `SmoothPageIndicator` tracks a PageController's scroll offset, while `AnimatedSmoothIndicator` takes an `activeIndex` and self-animates. The choice is about the source of truth: controller-backed movement versus an externally supplied index. This is more useful than simply naming another indicator library because both alternatives are documented by the same package and expose the same count and effect concepts.

Maintenance status can be stated from the repository metadata. The repository is not archived, and its last push was on 2026-08-21. There are no GitHub releases listed, so the repository does not currently provide a release history through that channel. The README references version `1.0.0` in several effect labels and links to a package version page, but no current release notes are shown. Upgrade planning should inspect `CHANGELOG.md` and `pubspec.yaml`, then verify the package's SDK constraints against the target Flutter project. The MIT license permits use and modification under its terms, but license obligations still depend on how the package is distributed and incorporated.

## Conclusion

Adopt smooth_page_indicator when a Flutter interface needs a small animated indicator tied to a PageController or a known active index. Do not choose it merely for a static or highly customized navigation control without first checking the selected effect and its documented properties. The first checks are Flutter and Dart compatibility in pubspec.yaml, whether the indicator can receive the correct controller or index, and whether the required color, spacing, axis, and animation behavior fit the interface.

## FAQ

### How does smooth_page_indicator follow a Flutter PageView?

The README says SmoothPageIndicator uses the PageController's scroll offset to animate the active dot. You supply the controller, item count, and an effect to the widget.

### Can smooth_page_indicator work without a PageController?

Yes. AnimatedSmoothIndicator is documented as self-animated and takes an active index instead of a PageController.

### Does smooth_page_indicator support vertical layouts?

Yes. The README documents `axisDirection: Axis.vertical` for SmoothPageIndicator and states that horizontal and vertical layouts are supported.

## Sources

- [Issues](https://github.com/Milad-Akarie/smooth_page_indicator/issues)
- [License: MIT](https://github.com/Milad-Akarie/smooth_page_indicator/blob/master/LICENSE)
- [Milad-Akarie/smooth_page_indicator on GitHub](https://github.com/Milad-Akarie/smooth_page_indicator)
- [README](https://github.com/Milad-Akarie/smooth_page_indicator/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/milad-akarie-smooth-page-indicator