k_gallery 1.0.0

A Telegram-style media gallery viewer for Flutter. Supports images, videos, and audio with pinch-to-zoom, thumbnail strip, swipe-to-dismiss, and more.

kGallery 🖼️

A high-performance, premium, and fully-featured media gallery viewer for Flutter. Inspired by the sleek experience of Telegram, kGallery supports images, videos, and audio content with smooth transitions and intuitive gestures.

✨ Features

• 🖼️ Multi-Media Support: Seamlessly view images, watch videos, and listen to audio.
• 🔍 Pinch-to-Zoom: Advanced image viewing with double-tap zoom and smooth pinch gestures.
• 🎞️ Thumbnail Strip: Animated, haptic-enabled thumbnail strip for quick navigation.
• 🖐️ Swipe-to-Dismiss: Natural vertical swipe gesture to exit the gallery with dynamic background fading.
• 📝 Draggable Info Panel: Overlays for titles and descriptions that can be expanded or collapsed.
• 📱 Adaptive Layout: Optimized for both mobile phones and tablets.
• 🎬 Video/Audio Controls: Integrated seekbar and playback controls powered by media_kit.
• 🌐 Connectivity Aware: Automatically checks for internet before playing remote media.
• 🎨 Fully Customizable: Inject your own progress widgets, action menus, and styles.

🚀 Getting Started

1. Add dependency

Add k_gallery to your pubspec.yaml:

dependencies:
  k_gallery: ^1.0.0

2. Platform Setup (Important!)

This package uses media_kit for video and audio playback. You must follow the native setup instructions for your target platforms:

• Android: Ensure minSdkVersion is 16 or higher.
• iOS: Add necessary permissions to Info.plist.
• macOS/Windows/Linux: Follow media_kit's requirements for native libraries.

Refer to the media_kit documentation for detailed setup.

3. Initialize

In your main.dart, initialize the gallery:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  KGallery.ensureInitialized(); // Initializes MediaKit
  runApp(MyApp());
}

🛠️ Usage

import 'package:k_gallery/k_gallery.dart';

// ... inside your widget ...

void _openGallery(BuildContext context) {
  Navigator.of(context).push(
    MaterialPageRoute(
      builder: (context) => KGallery(
        contentList: [
          GalleryItem(
            url: 'https://example.com/video.mp4',
            type: GalleryItemType.video,
            title: 'Big Buck Bunny',
            description: 'A classic animation.',
            thumbnailUrl: 'https://example.com/thumb.jpg',
          ),
          GalleryItem(
            url: 'https://example.com/photo.jpg',
            type: GalleryItemType.image,
            title: 'Sunset',
          ),
        ],
        initialIndex: 0,
        onClose: (index) => Navigator.of(context).pop(),
      ),
    ),
  );
}

⚙️ Customization

Parameter	Type	Description
contentList	List<GalleryItem>	Required. The list of media items.
initialIndex	int	Required. Index to start from.
progressWidget	Widget?	Custom loader for media items.
thumbProgressWidget	Widget?	Custom loader for thumbnails.
isZoomEnable	bool	Enable/disable pinch zoom (Default: true).
isSwipeToDismiss	bool	Enable/disable swipe down to exit (Default: true).
isHapticEnable	bool	Enable/disable haptics on thumbnails (Default: true).
actionMenuBuilder	Widget Function?	Build a custom menu in the top bar.
onClose	Function(int)?	Custom callback for when the gallery exits.

📄 License

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