Copyright ©️ Hadi — app_onboarding_guide

app_onboarding_guide

A premium, highly customizable guided tour and onboarding helper for Flutter that guides users through your app's features with beautiful animations, spotlight highlights, and responsive controls.

---

🎬 Demo

   

---

📱 Examples Preview

Example 1  |  Example 2  |  Example 3

---

✨ Key Features & Performance Optimization

• RTL & LTR Support: Automatically detects and mirrors layouts, alignments, buttons, gestures, and keyboard keys for Right-to-Left (RTL) locales.
• Auto-Scrolling Viewports: Smoothly scrolls parent viewports automatically to bring off-screen targets into view when focused.
• Dynamic Customization Dashboard: Live customization settings for colors, opacity, animations, and styles.
• Custom Progress Indicators: Choose between dynamic step Dots, an animated Progress Bar, or standard Numbered Labels ("Step N of M").
• Neon Spotlight Glow: Draw a soft glow/bloom ring around the spotlight cutout with customizable blur, color, and opacity.
• Ripple Effects: Sonar pulse wave ripples that draw attention to the focused widget.
• Gradients & Blurs: Supports radial/linear background gradient overlays and backdrop blurs (BackdropFilter).
• Transitions: Choose between multiple card entrance transitions (Fade, Slide Up, Slide Down, Scale Zoom).
• Auto-Play Timers: Programmatically advance to the next step after a set duration, complete with a circular visual countdown indicator.
• Keyboard & Gestures: Built-in horizontal swipe gestures and keyboard bindings (Arrow keys, Enter, Space, Escape).

---

📦 Installation

Add app_onboarding_guide to your pubspec.yaml dependencies:

dependencies:
  app_onboarding_guide: ^1.0.0

And import it in your Dart code:

import 'package:app_onboarding_guide/app_onboarding_guide.dart';

---

🚀 How to Use

Create your tour configurations by instantiating AppOnboardingGuide with a list of TargetFocus items:

void showMyTour(BuildContext context) {
  final targets = <TargetFocus>[
    TargetFocus(
      identify: "profile_avatar",
      keyTarget: profileKey, // GlobalKey
      shape: ShapeLightFocus.Circle,
      rippleEnable: true,
      contents: [
        TargetContent(
          align: ContentAlign.bottom,
          builder: (context, controller) {
            return TourContentCard(
              title: "Your Profile",
              description: "Tapping here lets you view and edit your profile settings easily.",
              controller: controller,
              nextText: "NEXT",
            );
          },
        ),
      ],
    ),
    TargetFocus(
      identify: "balance_card",
      keyTarget: balanceKey,
      shape: ShapeLightFocus.RRect,
      radius: 12.0,
      autoScroll: true, // Auto-scroll parent viewport if off-screen
      contents: [
        TargetContent(
          align: ContentAlign.end, // Mirrors to left in RTL, right in LTR
          builder: (context, controller) {
            return TourContentCard(
              title: "Wallet Balance",
              description: "Keep track of your transaction history and total funds here.",
              controller: controller,
              nextText: "FINISH",
            );
          },
        ),
      ],
    ),
  ];

  final tour = AppOnboardingGuide(
    targets: targets,
    colorShadow: Colors.deepPurple.shade900,
    opacityShadow: 0.8,
    showStepIndicator: true,
    stepIndicatorStyle: StepIndicatorStyle.dots,
    enableKeyboardNavigation: true,
    enableSwipeNavigation: true,
    onFinish: () {
      print("Tour finished!");
    },
  );

  tour.show(context: context);
}

---

## 📱 Interactive Example App

The `app_onboarding_guide` package comes with a comprehensive customizer dashboard example in the `example/` directory.

### Features of the Demo App
*   **Quick Styles**: Instantly test three distinct presets (Interactive, Auto-Play, and Luminous) to see the library's versatility.
*   **Live Customizer**: Tweak parameters on the fly, including:
    *   **Overlay Mode**: Solid shadows or custom multi-stop gradients.
    *   **Shadow Configuration**: Custom midnight/navy/crimson/black colors with a live opacity slider.
    *   **Progress Indicators**: Live switching between dynamic dots, linear progress bars, or numbered step counts.
    *   **Entrance Transitions**: Zoom scale, fade, and slide up content card animations.
    *   **Interactive Toggles**: Turn on/off spotlight neon glow, swipe gestures, keyboard keys, RTL layout mirroring, and target auto-scrolling.

### How to Run the Example App

Navigate to the `example` folder, fetch dependencies, and run:

```bash
cd example
flutter pub get
flutter run

---

⚙️ Customization & Parameters

TargetFocus Properties (Per Step)

Property	Type	Description	Default
identify	dynamic	A unique identifier for this step.	null
keyTarget	GlobalKey	The global key of the widget to highlight.	null
targetPosition	TargetPosition	Absolute screen offset and size if keyTarget is not used.	null
contents	List<TargetContent>	The overlay contents to render around the spotlight.	null
shape	ShapeLightFocus	The spotlight shape (Circle, RRect, Oval, Custom).	ShapeLightFocus.Circle
radius	double	Border corner radius (used with ShapeLightFocus.RRect).	null
borderSide	BorderSide	Draws an outline border around the spotlight.	null
color	Color	Overrides the global overlay background color for this step.	null
enableOverlayTab	bool	Enables tapping the background overlay to go to the next step.	false
enableTargetTab	bool	Enables tapping the target widget to go to the next step.	true
alignSkip	AlignmentGeometry	Custom position alignment for the Skip button.	AlignmentDirectional.bottomEnd
autoScroll	bool	Smoothly scrolls viewports to make the target visible.	true
scrollDuration	Duration	Scroll transition duration.	300ms
scrollCurve	Curve	Scroll transition animation curve.	Curves.easeInOut
glowEnable	bool	Draws a soft spotlight glow bloom ring.	false
glowColor	Color	Color of the spotlight glow ring.	null
glowRadius	double	Blur sigma radius of the glow.	16.0
glowOpacity	double	Opacity value of the glow (0.0 to 1.0).	0.35
autoAdvanceDuration	Duration	Duration before advancing automatically.	null
showAutoAdvanceIndicator	bool	Shows a circular progress timer countdown arc.	false

TargetContent Properties (Step Tooltip Card)

Property	Type	Description	Default
align	ContentAlign	Where to position content relative to target.	ContentAlign.bottom
padding	EdgeInsets	Padding spacing inside content.	EdgeInsets.all(20.0)
child	Widget	Static content widget.	null
builder	TargetContentBuilder	Dynamic builder callback offering controller access.	null
spacing	double	Gap space between the spotlight boundary and the content card.	null
expanded	bool	Whether content takes up full width constraint.	true
showArrow	bool	Draws a painter arrow pointing to the highlighted target.	false
arrowColor	Color	Custom color for the pointer arrow.	null

ContentAlign Values:

• ContentAlign.top: Positioned above the target.
• ContentAlign.bottom: Positioned below the target.
• ContentAlign.left: Positioned to the left of the target.
• ContentAlign.right: Positioned to the right of the target.
• ContentAlign.start: Direction-aware (Left in LTR, Right in RTL).
• ContentAlign.end: Direction-aware (Right in LTR, Left in RTL).
• ContentAlign.center: Centered on screen (ideal for full-screen welcoming slides).
• ContentAlign.custom: Positioned at precise screen offsets.

---

👤 Author & Maintainer

Hadi

• 📧 hadi7786x@gmail.com
• 🐙 github.com/Itsxhadi

---

🤝 Contributing & Community

Kindly submit a PR if you encounter any issues — and please make sure you're using stable channel releases.

Maintaining open source software ain't easy. If you've commercially used this software, please consider supporting its development:

Feel free to check it out and give it a ⭐️ if you love it. Follow me for more updates and projects.

Suggestions are warmly welcome & more updates are coming along the way... 🚀

---

Copyright ©️ Hadi — app_onboarding_guide