Wallpaper
A Flutter plugin that allows you to download an image from a URL and set it as wallpaper on Android.
The plugin supports setting wallpapers for:
- Home screen
- Lock screen
- Both screens
- System wallpaper
Features
- Download image from URL
- Track download progress
- Set wallpaper for home screen
- Set wallpaper for lock screen
- Set wallpaper for both screens
- Set system wallpaper
- Resize images before setting wallpaper
- Use modern opt-in fit modes for source-based wallpapers
- Read the platform-recommended wallpaper size
- Open the Android system wallpaper chooser
Installation
Add the plugin to your pubspec.yaml:
dependencies:
wallpaper: ^1.2.0
Then run:
flutter pub get
Android Configuration
The plugin manifest already declares the permissions it needs for downloading
network images and setting wallpapers:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.SET_WALLPAPER"/>
Downloaded images are stored in app-private cache, files, or external files
directories depending on DownloadLocation. Apps using the default workflow do
not need READ_EXTERNAL_STORAGE or WRITE_EXTERNAL_STORAGE, and they do not
need to add their own file_paths.xml.
Usage
Import the plugin:
import 'package:wallpaper/wallpaper.dart';
Recommended Wallpaper Size
Use the recommended size when choosing, generating, cropping, or downloading an
image for the current Android launcher:
final size = await Wallpaper.recommendedWallpaperSize();
print('${size.width} x ${size.height}');
Open Wallpaper Chooser
Open Android's built-in wallpaper chooser without passing a specific image:
await Wallpaper.openWallpaperChooser();
Download Image
final stream = Wallpaper.imageDownloadProgress(
imageUrl,
location: DownloadLocation.applicationDirectory,
);
stream.listen((progress) {
print(progress);
});
Typed Download Operation
Use download when you need typed progress, headers, timeouts, cache reuse, or
cancellation:
final operation = Wallpaper.download(
imageUrl,
options: const WallpaperDownloadOptions(
imageName: 'daily_wallpaper',
headers: {'Authorization': 'Bearer token'},
connectTimeout: Duration(seconds: 15),
receiveTimeout: Duration(seconds: 30),
cachePolicy: WallpaperCachePolicy.reuse,
),
);
operation.progress.listen((progress) {
print(progress.percentage);
});
final file = await operation.completed;
await Wallpaper.homeScreen(
imageName: file.imageName,
fileExtension: file.fileExtension,
location: file.location,
);
Cancel an active operation:
await operation.cancel();
Clear plugin-managed temporary downloads created by the typed download API:
await Wallpaper.clearCache();
Set Home Screen Wallpaper
await Wallpaper.homeScreen(
width: width,
height: height,
options: RequestSizeOptions.resizeFit,
location: DownloadLocation.applicationDirectory,
);
Set Lock Screen Wallpaper
await Wallpaper.lockScreen(
location: DownloadLocation.applicationDirectory,
);
Set Both Wallpapers
await Wallpaper.bothScreen(
location: DownloadLocation.applicationDirectory,
);
Set System Wallpaper
await Wallpaper.systemScreen(
location: DownloadLocation.applicationDirectory,
);
Set Wallpaper From a Local File
await Wallpaper.setFromFile(
file.path,
target: WallpaperTarget.home,
options: RequestSizeOptions.resizeFit,
fit: WallpaperFit.cover,
alignment: WallpaperAlignment.topCenter,
);
alignment is optional and defaults to center. It applies to WallpaperFit.cover
cropping and WallpaperFit.center placement.
Set Wallpaper From Bytes
await Wallpaper.setFromBytes(
imageBytes,
target: WallpaperTarget.both,
fileExtension: ImageFormat.png,
);
Set Wallpaper From an Asset
await Wallpaper.setFromAsset(
'assets/wallpaper.jpg',
target: WallpaperTarget.lock,
);
For assets bundled by another package:
await Wallpaper.setFromAsset(
'assets/wallpaper.jpg',
package: 'wallpaper_assets',
);
Unified Source API
Use setWallpaperFromSource when you prefer a typed result instead of catching
PlatformException from the legacy methods:
final result = await Wallpaper.setWallpaperFromSource(
source: WallpaperSource.file(file.path),
options: const WallpaperOptions(
target: WallpaperTarget.home,
fit: WallpaperFit.cover,
alignment: WallpaperAlignment.topCenter,
),
);
switch (result) {
case WallpaperSuccess(:final message):
print(message);
case WallpaperFailure(:final exception):
print('${exception.code}: ${exception.message}');
}
Example
final stream = Wallpaper.imageDownloadProgress(imageUrl);
stream.listen((progress) {
print("Downloading: $progress");
}, onDone: () async {
await Wallpaper.homeScreen(
width: 1080,
height: 1920,
options: RequestSizeOptions.resizeFit,
);
});
Supported Platform
| Platform |
Supported |
| Android |
✅ |
| iOS |
❌ |
Notes
- Internet connection is required to download images.
- Lock screen wallpaper requires Android 7.0+ (API 24).
- Behavior may vary depending on device manufacturer.
- Starting multiple downloads with the same
imageName writes to the same file.
Use unique names for concurrent downloads.
License
MIT License
