ky_guide 0.1.0
ky_guide: ^0.1.0 copied to clipboard
Guide feauture guide
ky_guide Guide #
A comprehensive and customizable onboarding system for Flutter applications that guides users through new features using beautiful overlays and tooltips.
✨ Features #
- 🎯 Target Any Widget - Highlight any existing widget in your app
- 🎨 Highly Customizable - Custom colors, content, and styling
- 📱 Responsive Design - Automatically adapts to different screen sizes
- 🔄 Smart Positioning - Tooltips position themselves optimally
- ⏭️ Skip Functionality - Users can skip onboarding anytime
- 🎭 Beautiful Animations - Smooth transitions between steps
- 🧩 Easy Integration - Works with existing apps without major changes
- 🚀 Lightweight - Minimal performance impact
📱 Screenshots #
Welcome Step | Feature Highlight | Custom Content |
---|---|---|
🚀 Getting Started #
Installation #
Add this to your package's pubspec.yaml
file:
dependencies:
ky_guide: ^0.1.0
Then run:
flutter pub get
Import #
import 'package:ky_guide/ky_guide.dart';
💡 Quick Start #
1. Create an GuideController #
class MyHomePage extends StatefulWidget {
@override
_MyHomePageState createState() => _MyHomePageState();
}
class _MyHomePageState extends State<MyHomePage> {
final GuideController _GuideController = GuideController();
}
2. Wrap Target Widgets #
// Create GlobalKeys for your target widgets
final GlobalKey _fabKey = GlobalKey();
final GlobalKey _menuKey = GlobalKey();
// Wrap widgets you want to highlight
GuideTarget(
onboardingKey: _fabKey,
child: FloatingActionButton(
onPressed: () {},
child: Icon(Icons.add),
),
)
3. Create Guide Steps #
void _startGuide() {
final steps = [
GuideStep(
targetKey: _fabKey,
title: 'Create New Items',
description: 'Tap this button to create new content.',
),
GuideStep(
targetKey: _menuKey,
title: 'Access Menu',
description: 'Find more options in this menu.',
backgroundColor: Colors.blue.shade50,
),
];
_GuideController.startGuide(steps);
}
4. Start Guide #
@override
void initState() {
super.initState();
// Start onboarding after first frame
WidgetsBinding.instance.addPostFrameCallback((_) {
_startGuide();
});
}
🎨 Customization #
Custom Step Content #
GuideStep(
targetKey: _buttonKey,
title: 'Pro Feature',
description: 'This is a premium feature.',
customContent: Container(
padding: EdgeInsets.all(12),
decoration: BoxDecoration(
color: Colors.amber.shade100,
borderRadius: BorderRadius.circular(8),
),
child: Row(
children: [
Icon(Icons.star, color: Colors.amber),
SizedBox(width: 8),
Text('Unlock with Pro!'),
],
),
),
backgroundColor: Colors.white,
showSkipButton: false, // Force users to see this step
)
Styling Options #
GuideStep(
targetKey: _targetKey,
title: 'Custom Style',
description: 'This step has custom styling.',
tooltipPadding: EdgeInsets.all(20),
backgroundColor: Colors.deepPurple.shade50,
borderRadius: 12.0,
)
🎮 Controller Methods #
Method | Description |
---|---|
startGuide(List<GuideStep> steps) |
Start onboarding with given steps |
nextStep() |
Move to next step |
previousStep() |
Move to previous step |
skipGuide() |
Skip entire onboarding |
finishGuide() |
Complete onboarding |
🎯 GuideStep Properties #
Property | Type | Default | Description |
---|---|---|---|
targetKey |
GlobalKey |
Required | Key of widget to highlight |
title |
String |
Required | Title text |
description |
String |
Required | Description text |
customContent |
Widget? |
null |
Additional custom content |
tooltipPadding |
EdgeInsets |
EdgeInsets.all(16) |
Tooltip padding |
backgroundColor |
Color? |
null |
Tooltip background color |
borderRadius |
double |
8.0 |
Highlight border radius |
showSkipButton |
bool |
true |
Show/hide skip button |
🔧 Advanced Usage #
Listen to Guide State #
_GuideController.addListener(() {
if (!_GuideController.isActive) {
print('Guide completed!');
// Save completion state, show celebration, etc.
}
});
Conditional Steps #
void _createConditionalGuide() {
List<GuideStep> steps = [
// Always show welcome
GuideStep(
targetKey: _welcomeKey,
title: 'Welcome!',
description: 'Let\'s get started.',
),
];
// Add premium feature step only for pro users
if (user.isPro) {
steps.add(GuideStep(
targetKey: _proFeatureKey,
title: 'Pro Feature',
description: 'This is available for pro users.',
));
}
_GuideController.startGuide(steps);
}
Multiple Guide Flows #
class GuideManager {
static const String FIRST_LAUNCH = 'first_launch';
static const String NEW_FEATURE = 'new_feature_v2';
static void showAppropriateGuide(BuildContext context) {
final prefs = SharedPreferences.getInstance();
if (!prefs.getBool(FIRST_LAUNCH, false)) {
_showFirstLaunchGuide();
prefs.setBool(FIRST_LAUNCH, true);
} else if (!prefs.getBool(NEW_FEATURE, false)) {
_showNewFeatureGuide();
prefs.setBool(NEW_FEATURE, true);
}
}
}
🧪 Testing #
import 'package:flutter_test/flutter_test.dart';
import 'package:ky_guide/ky_guide.dart';
void main() {
group('GuideController', () {
late GuideController controller;
setUp(() {
controller = GuideController();
});
test('should start with inactive state', () {
expect(controller.isActive, false);
expect(controller.currentStep, 0);
});
test('should activate when starting onboarding', () {
final steps = [
GuideStep(
targetKey: GlobalKey(),
title: 'Test',
description: 'Test description',
),
];
controller.startGuide(steps);
expect(controller.isActive, true);
});
});
}
🤝 Contributing #
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Development Setup #
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Make your changes
- Add tests for your changes
- Ensure tests pass (
flutter test
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
📋 Requirements #
- Flutter SDK:
>=3.0.0 <4.0.0
- Dart SDK:
>=2.17.0 <4.0.0
🐛 Issues #
If you encounter any issues, please file them on the GitHub issue tracker.
📄 License #
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments #
- Inspired by various onboarding libraries across different platforms
- Thanks to the Flutter community for feedback and contributions
- Special thanks to all contributors
📚 Related Packages #
- introduction_screen - Full-screen onboarding
- showcaseview - Feature showcasing
- tutorial_coach_mark - Tutorial overlay
Made with ❤️ by [Your Name]
---
## 📄 CHANGELOG.md
```markdown
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [1.0.0] - 2024-06-12
### 🎉 Initial Release
#### Added
- ✨ Complete onboarding system with overlay and tooltips
- 🎯 `GuideController` for managing onboarding flow
- 📝 `GuideStep` model for defining onboarding steps
- 🎨 `GuideTarget` widget for marking target elements
- 🔄 Navigation between steps (next, previous, skip, finish)
- 📱 Responsive tooltip positioning
- 🎨 Customizable styling (colors, padding, border radius)
- 📖 Custom content support for steps
- ⏭️ Configurable skip button per step
- 🌗 Dark overlay with spotlight effect on target widgets
- 📚 Comprehensive API documentation
- 🧪 Example implementation
- 🔧 TypeScript-like documentation with examples
#### Features
- **Smart Positioning**: Tooltips automatically position above or below targets
- **Customizable Content**: Add custom widgets to any step
- **Skip Functionality**: Allow users to skip onboarding entirely
- **Step Control**: Navigate forward, backward, or jump to finish
- **Responsive Design**: Works on all screen sizes
- **Easy Integration**: Minimal code changes to existing apps
- **Performance Optimized**: Efficient overlay rendering and updates
#### Developer Experience
- 📖 Complete API documentation with examples
- 🎯 Type-safe implementation
- 🧩 Easy integration with existing Flutter apps
- 🔧 Highly customizable and extensible
- 📱 Works with any existing Flutter widgets
### 📋 Requirements
- Flutter: `>=3.0.0 <4.0.0`
- Dart: `>=2.17.0 <4.0.0`
### 🔗 Links
- [Documentation](https://pub.dev/documentation/ky_guide/latest/)
- [Example](https://pub.dev/packages/ky_guide/example)
- [GitHub Repository](https://github.com/bhangun/ky_guide)
---
## [Unreleased]
### 🚧 Planned Features
- 🎥 Animation customization options
- 🎵 Sound effects support
- 📊 Analytics integration
- 🌍 Internationalization support
- 🎨 More built-in tooltip themes
- 📱 Platform-specific adaptations
- 🔄 Gesture-based navigation
- 💾 Automatic progress persistence
### 🐛 Known Issues
- None currently reported
---
## Release Notes Format
Each release follows this structure:
### [Version] - Date
#### Added ✨
- New features and capabilities
#### Changed 🔄
- Changes to existing functionality
#### Deprecated ⚠️
- Features marked for removal
#### Removed 🗑️
- Removed features
#### Fixed 🐛
- Bug fixes and corrections
#### Security 🔒
- Security-related changes
---
**Note**: This project follows [Semantic Versioning](https://semver.org/). Given a version number MAJOR.MINOR.PATCH:
- **MAJOR** version changes for incompatible API changes
- **MINOR** version changes for backward-compatible functionality additions
- **PATCH** version changes for backward-compatible bug fixes
🚀 Publishing Checklist #
Before publishing to pub.dev, ensure:
- ❌ All files are in correct directory structure
- ❌
pubspec.yaml
has correct version and metadata - ❌ README.md is comprehensive with examples
- ❌ CHANGELOG.md documents all changes
- ❌ LICENSE file is included
- ❌ Tests are written and passing
- ❌ Documentation is complete
- ❌ Example app works correctly
- ❌ No sensitive information in code
- ❌ Package analysis passes (
dart pub publish --dry-run
)
📦 Publishing Command #
# Dry run to check for issues
dart pub publish --dry-run
# Publish to pub.dev
dart pub publish
This package is now ready for publication to pub.dev with all the necessary files, documentation, and structure!