Flutter Wizard Kit 🧙

A comprehensive Flutter package for multi-step form wizards with customizable steps, validation, and navigation controls.

Features ✨

  • 📋 Multi-Step Forms: Create complex multi-step forms with ease
  • 🎮 Smart Controller: Comprehensive state management and navigation
  • 📊 Progress Tracking: Visual progress indicators with multiple styles
  • 🎯 Navigation Controls: Previous, next, skip, and complete buttons
  • ✅ Validation Support: Built-in validation with error handling
  • 📱 Platform Adaptive: Automatically adapts to iOS and Android design patterns
  • 🎨 Highly Customizable: Colors, spacing, sizing, and styling options
  • ♿ Accessibility Ready: Proper semantic structure and screen reader support
  • 🌍 Localization Ready: All text is customizable for different languages
  • ⚡ Performance Optimized: Efficient step rendering and state management

Installation 📦

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_wizard_kit: ^1.0.0

Then run:

flutter pub get

Usage 🚀

Basic Wizard Setup

import 'package:flutter_wizard_kit/flutter_wizard_kit.dart';

class MyWizardScreen extends StatefulWidget {
  @override
  _MyWizardScreenState createState() => _MyWizardScreenState();
}

class _MyWizardScreenState extends State<MyWizardScreen> {
  late WizardController _controller;

  @override
  void initState() {
    super.initState();
    _controller = WizardController(
      steps: [
        WizardData(stepId: 'step1', title: 'Personal Information'),
        WizardData(stepId: 'step2', title: 'Contact Details'),
        WizardData(stepId: 'step3', title: 'Preferences'),
      ],
      onStepChanged: (index, data) => print('Step $index: ${data.title}'),
      onCompleted: () => _navigateToSuccessScreen(),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Setup Wizard')),
      body: WizardWidget(
        controller: _controller,
        steps: [
          WizardStep(
            data: WizardData(
              stepId: 'step1',
              title: 'Personal Information',
              subtitle: 'Tell us about yourself',
            ),
            content: PersonalInfoForm(),
          ),
          WizardStep(
            data: WizardData(
              stepId: 'step2',
              title: 'Contact Details',
              subtitle: 'How can we reach you?',
            ),
            content: ContactDetailsForm(),
          ),
          WizardStep(
            data: WizardData(
              stepId: 'step3',
              title: 'Preferences',
              subtitle: 'Customize your experience',
            ),
            content: PreferencesForm(),
          ),
        ],
        showProgress: true,
        showNavigation: true,
        allowSkip: true,
      ),
    );
  }

  void _navigateToSuccessScreen() {
    Navigator.pushReplacement(
      context,
      MaterialPageRoute(builder: (context) => SuccessScreen()),
    );
  }
}

Advanced Wizard with Custom Validation

final controller = WizardController(
  steps: [
    WizardData(
      stepId: 'personal',
      title: 'Personal Info',
      isOptional: false,
      isSkippable: false,
    ),
    WizardData(
      stepId: 'contact',
      title: 'Contact Info',
      isOptional: false,
      isSkippable: true,
    ),
    WizardData(
      stepId: 'preferences',
      title: 'Preferences',
      isOptional: true,
      isSkippable: true,
    ),
  ],
  onStepChanged: (index, data) {
    print('Current step: ${data.title}');
  },
  onCompleted: () {
    print('Wizard completed!');
    _saveWizardData();
  },
  allowSkip: true,
  requireValidation: true,
);

// Update step data
controller.updateStepData('personal', {
  'firstName': 'John',
  'lastName': 'Doe',
  'email': 'john.doe@example.com',
});

// Update validation
controller.updateStepValidation('personal', true);

// Mark step as completed
controller.markStepCompleted('personal');

Custom Progress Indicator

WizardProgress(
  controller: _controller,
  style: ProgressStyle.steps,
  color: Colors.blue,
  backgroundColor: Colors.grey.shade300,
  height: 12.0,
  showPercentage: true,
  showStepNumbers: true,
  borderRadius: 6.0,
)

Custom Navigation Controls

WizardNavigation(
  controller: _controller,
  allowSkip: true,
  previousText: 'Back',
  nextText: 'Continue',
  skipText: 'Skip This Step',
  completeText: 'Finish Setup',
  color: Colors.blue,
  height: 55.0,
  borderRadius: 16.0,
  previousIcon: Icons.arrow_back_ios,
  nextIcon: Icons.arrow_forward_ios,
  completeIcon: Icons.check_circle,
)

Step with Custom Content

WizardStep(
  data: WizardData(
    stepId: 'custom_step',
    title: 'Custom Step',
    subtitle: 'This step has custom content',
  ),
  content: Column(
    children: [
      Text('Custom step content'),
      ElevatedButton(
        onPressed: () => _handleCustomAction(),
        child: Text('Custom Action'),
      ),
    ],
  ),
  onDataChanged: (data) => print('Step data changed: $data'),
  onValidationChanged: (isValid) => print('Validation: $isValid'),
  onCompleted: (data) => print('Step completed: $data'),
)

Customization 🎨

Wizard Styling

WizardWidget(
  controller: _controller,
  steps: _steps,
  showProgress: true,
  showNavigation: true,
  progressPosition: ProgressPosition.top,
  navigationPosition: NavigationPosition.bottom,
  padding: EdgeInsets.all(24),
  stepSpacing: 32,
  progressSpacing: 20,
  navigationSpacing: 20,
  backgroundColor: Colors.white,
  stepBackgroundColor: Colors.grey.shade50,
  progressColor: Colors.blue,
  navigationColor: Colors.blue,
  borderRadius: 16,
  elevation: 4,
  shadowColor: Colors.black.withOpacity(0.1),
)

Progress Indicator Styles

// Linear progress
WizardProgress(
  style: ProgressStyle.linear,
  color: Colors.blue,
  backgroundColor: Colors.grey.shade300,
  height: 8.0,
  borderRadius: 4.0,
  showPercentage: true,
)

// Circular progress
WizardProgress(
  style: ProgressStyle.circular,
  color: Colors.blue,
  backgroundColor: Colors.grey.shade300,
  height: 6.0,
  width: 120.0,
  showPercentage: true,
)

// Steps progress
WizardProgress(
  style: ProgressStyle.steps,
  color: Colors.blue,
  backgroundColor: Colors.grey.shade300,
  height: 10.0,
  showStepNumbers: true,
)

WizardNavigation(
  controller: _controller,
  previousText: 'Previous',
  nextText: 'Next',
  skipText: 'Skip',
  completeText: 'Complete',
  color: Colors.blue,
  textColor: Colors.white,
  backgroundColor: Colors.white,
  borderColor: Colors.blue,
  height: 50.0,
  borderRadius: 12.0,
  buttonSpacing: 16.0,
  previousIcon: Icons.arrow_back,
  nextIcon: Icons.arrow_forward,
  skipIcon: Icons.skip_next,
  completeIcon: Icons.check,
  iconSize: 20.0,
  iconSpacing: 8.0,
)

Widgets 📱

WizardWidget

Main wizard container that manages step rendering, progress, and navigation.

WizardStep

Individual wizard step with customizable content and validation.

WizardController

Controller for managing wizard state, navigation, and data.

WizardProgress

Progress indicator with multiple styles (linear, circular, steps).

WizardNavigation

Navigation controls with previous, next, skip, and complete buttons.

WizardData

Data model for wizard step information and state.

Dependencies 📋

  • flutter: SDK
  • flutter_platform_widgets: Platform-adaptive widgets

Contributing 🤝

Contributions are welcome! Please feel free to submit a Pull Request.

License 📄

This project is licensed under the MIT License - see the LICENSE file for details.

Support 💬

If you encounter any problems or have suggestions, please file an issue at the GitHub repository.

Made with ❤️ by seifmoustafa

Libraries

flutter_wizard_kit
A comprehensive Flutter package for multi-step form wizards with customizable steps, validation, and navigation controls.