expo-alternate-app-icons

Alternative icons must follow the same format as your default app icon:

• Format: .png
• Dimensions: Square, 1024x1024 px resolution
• iOS: Should not have a transparency layer.
• Android (Adaptive Icon): Requires a foregroundImage and a backgroundColor for the background fill.

Install the library using the Expo CLI. Ensure your project is running Expo SDK 51 or higher.

npx expo install expo-alternate-app-icons

When providing detailed configuration for icons, use the AlternateIcon type. This allows you to explicitly map a name to a specific file path.

If you provide an array of strings instead of AlternateIcon objects, the plugin will treat the strings as paths and automatically derive the icon names using PascalCase.

// Using AlternateIcon objects
const icons: AlternateIcon[] = [
  { name: 'HolidayTheme', path: './assets/holiday.png' }
];

// Using string paths (names are derived via PascalCase)
const iconPaths: string[] = ['./assets/holiday.png'];

When defining an AlternateIcon, the ios property can be configured as an iOSVariantsIcon object. This allows you to specify different icon images for the different iOS system appearance modes: light, dark, and tinted. The keys in the object must be one of these three strings, and the values must be the paths to the icon files.

// Example of an iOSVariantsIcon configuration
const iosIcons: iOSVariantsIcon = {
  light: './assets/icon-light.png',
  dark: './assets/icon-dark.png',
  tinted: './assets/icon-tinted.png'
};

The resetAppIcon() function is a convenience shortcut for setAlternateAppIcon(null). It resets the app icon to the default one.

await resetAppIcon();

The boolean supportsAlternateIcons indicates whether the current device supports the alternate icon feature.

if (supportsAlternateIcons) {
  // logic to allow icon switching
}

Use getAppIconName() to retrieve the name of the currently active app icon. Returns null if the default icon is active.

const currentIcon = getAppIconName();

Use setAlternateAppIcon(name) to switch the app icon. Pass the PascalCase name of the icon defined in your app.json. To reset the icon to the default app icon, pass null.

// Set icon to IconA
await setAlternateAppIcon("IconA");

// Reset to default icon
await setAlternateAppIcon(null);

When using npm v7+ in a monorepo or a project where react-native might be installed in a parent directory, you may encounter incompatible versions of react-native being bundled. To prevent this, add a RegExp to config.resolver.blockList that targets the parent node_modules/react-native path. This ensures the bundler only uses the local version.

config.resolver.blockList = [
  ...Array.from(config.resolver.blockList ?? []),
  new RegExp(path.resolve('..', 'node_modules', 'react-native')),
];

In monorepo setups, you may need to explicitly define where Metro looks for modules and which folders it should watch to ensure dependencies in parent directories are correctly resolved and tracked. Use config.resolver.nodeModulesPaths to include both local and parent node_modules directories, and config.watchFolders to include the parent directory.

config.resolver.nodeModulesPaths = [
  path.resolve(__dirname, './node_modules'),
  path.resolve(__dirname, '../node_modules'),
];

config.watchFolders = [path.resolve(__dirname, '..')];

The expo-module.config.json file defines the native module mappings for the expo-alternate-app-icons library across different platforms. This configuration ensures that the Expo autolinking mechanism correctly identifies and links the native modules for iOS and Android.

• iOS: Uses the ExpoAlternateAppIconsModule.
• Android: Uses the expo.modules.alternateappicons.ExpoAlternateAppIconsModule.

{
  "platforms": ["ios", "android"],
  "ios": {
    "modules": ["ExpoAlternateAppIconsModule"]
  },
  "android": {
    "modules": ["expo.modules.alternateappicons.ExpoAlternateAppIconsModule"]
  }
}