react-native-wallpapers

A comprehensive React Native library for Android wallpaper management. Set static, live (GIF), video, and 3D parallax wallpapers with full customization — blur, brightness, color filters, crop, auto-rotation, and more.

Android only. iOS does not support programmatic wallpaper setting.

Installation

npm install react-native-wallpapers

Then rebuild your Android app:

cd android && ./gradlew clean && cd ..
npx react-native run-android

Register the package manually (if not using auto-linking)

In android/app/src/main/java/.../MainApplication.kt:

import com.rnwallpapers.RNWallpapersPackage

override fun getPackages(): List<ReactPackage> = listOf(
    MainReactPackage(),
    RNWallpapersPackage(),  // ← add this
)

Add WorkManager dependency (required for Auto Change)

In android/app/build.gradle:

dependencies {
    implementation "androidx.work:work-runtime-ktx:2.9.0"
}

Permissions

Add to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.SET_WALLPAPER" />
<uses-permission android:name="android.permission.INTERNET" />

<!-- For saving wallpapers to gallery -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
  android:maxSdkVersion="28" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

Quick Start

import {
  setWallpaper,
  WallpaperTarget,
  WallpaperType,
  ColorFilter,
} from 'react-native-wallpapers';

// Set a static wallpaper on home screen
await setWallpaper('https://example.com/image.jpg');

// Set on both screens
await setWallpaper('https://example.com/image.jpg', {
  target: WallpaperTarget.BOTH,
});

API Reference

setWallpaper(source, options?)

The main function. Sets a wallpaper from a URL or local file path.

const result = await setWallpaper(source, options);
// result.success → boolean
// result.error   → { code, message } if failed

| Parameter | Type | Description | |---|---|---| | source | string | Remote URL or local file:// path | | options | SetWallpaperOptions | Customization options (see below) |

SetWallpaperOptions

| Option | Type | Default | Description | |---|---|---|---| | target | WallpaperTarget | HOME | Where to set: HOME, LOCK, BOTH | | type | WallpaperType | STATIC | STATIC, LIVE, VIDEO, PARALLAX | | fit | WallpaperFit | FILL | FILL, FIT, STRETCH, CENTER, TILE | | blurRadius | number | 0 | Blur amount 0–25 | | brightness | number | 0 | -1.0 (dark) to 1.0 (bright) | | opacity | number | 1.0 | 0.0 to 1.0 | | colorFilter | ColorFilterOptions | — | Apply color overlay | | crop | CropOptions | — | Crop before setting | | parallax | ParallaxOptions | — | 3D parallax settings | | video | VideoWallpaperOptions | — | Video playback settings | | live | LiveWallpaperOptions | — | GIF playback settings |

Shorthand Functions

// Home screen only
await setHomeWallpaper(source, options);

// Lock screen only
await setLockWallpaper(source, options);

// Both screens
await setBothWallpapers(source, options);

// Different wallpapers for each screen
await setDualWallpaper(homeSource, lockSource, options);

downloadWallpaper(url, options?)

Download a wallpaper to device storage.

const result = await downloadWallpaper('https://example.com/image.jpg', {
  filename: 'my_wallpaper',
  saveDirectory: 'Pictures/MyApp',
  showNotification: true,
});

console.log(result.filePath);  // /storage/emulated/0/Pictures/MyApp/my_wallpaper.jpg
console.log(result.fileSize);  // size in bytes

startAutoChange(options)

Automatically rotate wallpapers on a schedule using WorkManager (persists across app restarts).

await startAutoChange({
  sources: [
    'https://example.com/1.jpg',
    'https://example.com/2.jpg',
    'https://example.com/3.jpg',
  ],
  intervalMinutes: 60,   // every 1 hour
  target: WallpaperTarget.HOME,
  shuffle: true,
});

stopAutoChange()

await stopAutoChange();

getAutoChangeStatus()

const status = await getAutoChangeStatus();
// status.isActive      → boolean
// status.currentIndex  → number
// status.totalSources  → number
// status.intervalMinutes → number

clearWallpaper(target?)

Reset to system default wallpaper.

await clearWallpaper(WallpaperTarget.BOTH);

getDeviceCapabilities()

Check what the device supports before enabling advanced features.

const caps = await getDeviceCapabilities();

if (caps.supportsVideoWallpaper) {
  // show video wallpaper option
}
if (caps.supportsParallax) {
  // show parallax option
}

console.log(caps.screenWidth, caps.screenHeight);

onWallpaperChanged(listener)

Listen for wallpaper change events.

const unsubscribe = onWallpaperChanged((event) => {
  console.log('Changed:', event.target, event.type, event.timestamp);
});

// Cleanup
unsubscribe();

Examples

Live GIF Wallpaper

await setWallpaper('https://example.com/animated.gif', {
  type: WallpaperType.LIVE,
  target: WallpaperTarget.HOME,
  live: {
    speed: 1.2,
    loopCount: 0, // infinite
  },
});

3D Parallax Wallpaper

await setWallpaper('https://example.com/image.jpg', {
  type: WallpaperType.PARALLAX,
  parallax: {
    intensity: 0.7,
    useGyroscope: true,
    maxOffset: 40,
  },
});

Video Wallpaper

await setWallpaper('https://example.com/video.mp4', {
  type: WallpaperType.VIDEO,
  video: {
    loop: true,
    muted: true,
    speed: 1.0,
    startTime: 2, // start at 2 seconds
  },
});

With Color Filter + Blur

await setWallpaper('https://example.com/image.jpg', {
  target: WallpaperTarget.BOTH,
  blurRadius: 8,
  colorFilter: {
    type: ColorFilter.DARK,
    intensity: 0.4,
  },
  brightness: -0.1,
});

Error Handling

import { WallpaperError } from 'react-native-wallpapers';

const result = await setWallpaper('https://example.com/image.jpg');

if (!result.success) {
  switch (result.error?.code) {
    case WallpaperError.PERMISSION_DENIED:
      console.log('No permission to set wallpaper');
      break;
    case WallpaperError.DOWNLOAD_FAILED:
      console.log('Could not download image');
      break;
    case WallpaperError.FILE_NOT_FOUND:
      console.log('File does not exist');
      break;
    default:
      console.log('Error:', result.error?.message);
  }
}

Enums

WallpaperTarget  → HOME | LOCK | BOTH
WallpaperType    → STATIC | LIVE | VIDEO | PARALLAX
WallpaperFit     → FILL | FIT | STRETCH | CENTER | TILE
ColorFilter      → NONE | WARM | COOL | DARK | LIGHT | GRAYSCALE | SEPIA | VINTAGE
WallpaperError   → PERMISSION_DENIED | FILE_NOT_FOUND | UNSUPPORTED_FORMAT | SET_FAILED | DOWNLOAD_FAILED | UNKNOWN

Android Version Support

| Feature | Min Android | |---|---| | Static wallpaper | Android 5.0 (API 21) | | Lock screen wallpaper | Android 7.0 (API 24) | | Video wallpaper | Android 8.0 (API 26) | | Live/GIF wallpaper | Android 5.0 (API 21) | | Parallax wallpaper | Android 5.0 (API 21) | | Auto-change (WorkManager) | Android 5.0 (API 21) |

License

MIT