@gamaroff/ionic-wizard-bubbles

A wizard bubble plugin for Ionic applications that helps guide users through your app's features.

Features

• 🎯 Highlight specific elements on the page
• 💬 Show informative bubbles with custom text
• 🎨 Fully customizable themes
• 📱 Cross-platform support (Web, iOS*, Android WebView)
• 🔄 Step-by-step navigation
• 🎉 Optional icons for each step
• 📱 Smart positioning for mobile screens
• 🔍 Debug mode for troubleshooting

*Note: iOS native implementation is currently a stub. Web implementation works in iOS WebView.

Installation

npm install @gamaroff/ionic-wizard-bubbles

Platform Setup

Web

No additional setup required. The plugin works out of the box.

Android (WebView)

The plugin works in Android's WebView environment. For optimal performance:

1. Add the viewport meta tag to your index.html:

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">

2. Use ngAfterViewInit for initialization in your Angular component:

import { Component, AfterViewInit } from '@angular/core';
import { WizardBubble } from '@gamaroff/ionic-wizard-bubbles';

@Component({
  selector: 'app-home',
  template: `
    <ion-content>
      <div id="feature1">Feature 1</div>
      <div id="feature2">Feature 2</div>
    </ion-content>
  `
})
export class HomePage implements AfterViewInit {
  ngAfterViewInit() {
    // Wait for the view to be fully rendered
    setTimeout(() => {
      WizardBubble.show({
        steps: [
          {
            targetId: 'feature1',
            text: 'This is an amazing feature!',
            icon: '🚀'
          },
          {
            targetId: 'feature2',
            text: 'And here is another cool thing!'
          }
        ],
        buttonText: {
          next: 'Continue',
          finish: 'Got it!'
        },
        theme: {
          backgroundColor: '#ffffff',
          textColor: '#333333',
          buttonColor: '#007bff',
          buttonTextColor: '#ffffff',
          highlightColor: '#007bff',
          borderRadius: '12px'
        }
      });
    }, 1000);
  }
}

iOS (WebView)

Same setup as Android - the web implementation works in iOS WebView.

Debugging in Android WebView

To view debug logs and troubleshoot issues:

1. Connect your Android device to your computer
2. Open Chrome on your computer
3. Navigate to chrome://inspect/#devices
4. Find your app in the list and click "inspect"
5. Check the console for detailed logs about element positioning and visibility

API Reference

WizardBubbleOptions Interface

interface WizardBubbleOptions {
  steps: WizardBubbleStep[];
  buttonText?: {
    next?: string;
    finish?: string;
  };
  theme?: {
    backgroundColor?: string;
    textColor?: string;
    buttonColor?: string;
    buttonTextColor?: string;
    highlightColor?: string;
    borderRadius?: string;
  };
}

interface WizardBubbleStep {
  targetId: string;
  text: string;
  icon?: string;  // Emoji or text icon
}

Methods

show(options: WizardBubbleOptions): Promise

Shows the wizard bubble with the specified options. Features include:

• Smart positioning that adjusts based on screen space
• Automatic repositioning for scrolled content
• Touch-optimized for mobile devices
• High z-index to ensure visibility in WebViews

next(): Promise<{ isFinished: boolean }>

Advances to the next step. Returns an object with isFinished indicating whether the wizard has completed.

hide(): Promise

Manually hides the wizard bubble.

Platform Support

| Feature | Web | iOS WebView | Android WebView | iOS Native | Android Native | |---------|-----|-------------|----------------|------------|----------------| | Show Bubble | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | | Hide Bubble | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | | Navigation | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | | Theming | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | | Element Highlighting | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | | Smart Positioning | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |

✅ = Fully supported ⚠️ = Stub implementation (no visual elements)

Troubleshooting

Bubble Not Visible

1. Check element IDs match exactly
2. Ensure the view is fully rendered (use setTimeout)
3. Verify z-index conflicts with other elements
4. Check Chrome DevTools for error messages
5. Ensure the target element is in the viewport

Positioning Issues

1. Verify viewport meta tag is present
2. Check if target element is properly positioned
3. Ensure no CSS transforms affecting positioning
4. Check Chrome DevTools console for positioning logs

Contributing

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

License

MIT