wallpapers_kit

A Flutter wallpaper gallery toolkit: grid, category strip, full-screen viewer, favorites, set-as-wallpaper, and download — themed automatically from your app's ThemeData (light/dark).

No bundled wallpapers, no ads. You supply the wallpaper list and, optionally, your own ad-gating logic.

Install

dependencies:
  wallpapers_kit: ^0.1.0

Android

android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
        android:maxSdkVersion="29" tools:node="replace" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
        android:maxSdkVersion="32" tools:node="replace" />
</manifest>

android/app/build.gradle.kts:

android {
    compileSdk = maxOf(flutter.compileSdkVersion, 37)
}

iOS

ios/Runner/Info.plist:

<key>NSPhotoLibraryAddUsageDescription</key>
<string>Used to save downloaded wallpapers to your photo library.</string>

ios/Podfile, inside post_install's installer.pods_project.targets.each do |target| loop:

target.build_configurations.each do |config|
  config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)', 'PERMISSION_PHOTOS_ADD_ONLY=1']
end

Usage

import 'package:wallpapers_kit/wallpapers_kit.dart';

final wallpapers = [
  const Wallpaper(url: 'https://example.com/1.jpg', category: 'Nature'),
  const Wallpaper(url: 'https://example.com/2.jpg', category: 'Nature'),
];

Scaffold(
  appBar: AppBar(title: const Text('Wallpapers')),
  body: WallpaperGridView(
    wallpapers: wallpapers,
    favoritesStore: SharedPreferencesFavoritesStore(),
  ),
);

Wrap your app in MaterialApp(theme: ..., darkTheme: ..., themeMode: ...) and every wallpapers_kit widget follows along — no extra wiring.

Loading wallpapers from an API

Future<List<Wallpaper>> fetchCatalog() async {
  final response = await http.get(Uri.parse('https://your-api.example.com/config'));
  final raw = (jsonDecode(response.body)['wallpapers'] as Map).cast<String, dynamic>();
  return raw.entries
      .expand((e) => (e.value as List)
          .map((url) => Wallpaper(url: url as String, category: e.key)))
      .toList();
}

FutureBuilder<List<Wallpaper>>(
  future: fetchCatalog(),
  builder: (context, snapshot) {
    if (!snapshot.hasData) return const Center(child: CircularProgressIndicator());
    return WallpaperGridView(wallpapers: snapshot.data!);
  },
);

Gating actions behind your own ads

WallpaperGridView(
  wallpapers: wallpapers,
  onBeforeDownload: () async => MyAdManager.showRewarded(),
  onBeforeSetWallpaper: () async => MyAdManager.showRewarded(),
);

Categories

WallpaperGridView(
  wallpapers: allWallpapers,
  header: WallpaperCategoryStrip(
    categories: [WallpaperCategory(title: 'Nature', thumbnailUrl: natureWallpapers.first.gridUrl)],
    onCategoryTap: (category) => Navigator.push(
      context,
      MaterialPageRoute(
        builder: (_) => Scaffold(
          appBar: AppBar(title: Text(category.title)),
          body: WallpaperGridView(wallpapers: byCategory[category.title]!),
        ),
      ),
    ),
  ),
);

Theming

Pass style: WallpapersKitStyle(...) to override specific colors; leave it out and every widget follows Theme.of(context) automatically.

Full example

See example/lib/main.dart.