staged_stepper 0.1.0

A staged, animated stepper with timed steps and connecting bars.

staged_stepper

A staged, timed stepper widget with animated connecting bars. Useful for multi-phase operations like verification, confirmation, and completion.

Features

• N steps with individual durations
• Auto progression on timers
• Animated bar fill between steps
• Customizable circles and bars via builders
• Status titles per step and on completion
• Imperative control via StagedStepperController

Install

dependencies:
  staged_stepper: ^0.1.0

or

flutter pub add staged_stepper

Quick start

final controller = StagedStepperController();

StagedStepper(
  controller: controller,
  steps: const [
    StagedStep(duration: Duration(seconds: 3), titleWhenActive: 'Checking...', titleWhenDone: 'Checked'),
    StagedStep(duration: Duration(seconds: 3), titleWhenActive: 'Confirming...', titleWhenDone: 'Confirmed'),
    StagedStep(duration: Duration(seconds: 3)),
  ],
  initialTitle: 'Checking...',
  finalTitle: 'Confirmed',
  circleBuilder: (ctx, state) => null, // default visuals
  barBuilder: (ctx, active) => null,   // default visuals
  onComplete: () { /* optional */ },
);
// later
controller.start();

API

StagedStepper

Prop	Type	Default	Description
steps	List<StagedStep>	required	Ordered steps with durations and optional titles.
initialTitle	String	required	Title before first step finishes.
finalTitle	String?	null	Title after the last step completes.
circleBuilder	Widget Function(BuildContext, StepState)	required	Return null to use default rendering.
barBuilder	Widget Function(BuildContext, bool)	required	Return null to use default rendering.
controller	StagedStepperController?	null	Call start() to run.
onComplete	VoidCallback?	null	Called after the last step.
barCurve	Curve	Curves.easeInOut	Curve for bar fill animation.
barFillDuration	Duration	600ms	Duration for bar fill animation.
padding	EdgeInsetsGeometry	EdgeInsets.all(32)	Outer padding.
gap	double	8	Horizontal gap around bars.

StagedStep

Field	Type	Description
duration	Duration	How long this step “loads”.
titleWhenActive	String?	Title while this step is active.
titleWhenDone	String?	Title when this step finishes.

StepState

waiting, loading, done.

StagedStepperController

• Future<void> start() — runs the sequence once.

Customizing visuals

Provide builders. Return null to fallback to defaults.

circleBuilder: (ctx, state) {
  final cs = Theme.of(ctx).colorScheme;
  return switch (state) {
    StepState.waiting => Container(
      width: 30, height: 30,
      decoration: BoxDecoration(shape: BoxShape.circle, border: Border.all(color: cs.outline, width: 2)),
    ),
    StepState.loading => const SizedBox(
      width: 30, height: 30, child: CircularProgressIndicator(strokeWidth: 2.5)),
    StepState.done => CircleAvatar(radius: 15, backgroundColor: cs.primary, child: Icon(Icons.check, size: 16, color: cs.onPrimary)),
  };
},
barBuilder: (ctx, active) => LayoutBuilder(
  builder: (_, c) => Stack(
    alignment: Alignment.centerLeft,
    children: [
      Container(height: 4, color: Theme.of(ctx).colorScheme.outline),
      AnimatedContainer(
        duration: const Duration(milliseconds: 600),
        curve: Curves.easeInOut,
        height: 4,
        width: active ? c.maxWidth : 0,
        color: Theme.of(ctx).colorScheme.primary,
      ),
    ],
  ),
),

Example app

See /example. Run:

cd example
flutter run

FAQ

Can it autoplay?
Not yet. Use controller.start() in initState if you want immediate start.

Multiple runs?
Rebuild a new StagedStepper or add a reset() in your fork. A controller reset() may land in a later minor version.

Roadmap

• autoplay flag
• reset() and jumpTo(int)
• Vertical layout
• Accessibility hints per step
• Expose theming hooks: sizes, strokeWidth, colors in builders.
• Add onStepChange(int index, StepState state).

License

MIT