Expo Alternate App Icons

Expo Alternate App Icons is a library that allows you to easily switch between different app icons in your Expo project.

Platform Compatibility

| Android Device | Android Emulator | iOS Device | iOS Simulator | Web | | -------------- | ---------------- | ---------- | ------------- | --- | | ✅ | ✅ | ✅ | ✅ | ❌ |

Introduction

Customizing app icons can be a valuable way to provide users with a personalized experience for your app. This library simplifies the process of implementing alternate app icons in your Expo project.

Demo

Installation

To get started, install the library using Expo CLI:

npx expo install expo-alternate-app-icons

Ensure your project is running Expo SDK 51+.

How To Use

This package contains an Expo Plugin that copies your alternative icons to native projects.

1. Add expo-alternate-app-icons to the plugins array inside your app.json.
2. The second item in the array accepts an array with details about your alternate icons.
3. Prebuild a project using npx expo prebuild --clean to apply the plugin changes.

// app.json
{
  // ...
  "plugins": [
    // ...
    [
      "expo-alternate-app-icons",
      [
        {
          "name": "IconA", // The name of the alternate icon
          "ios": "./assets/icon-a.png", // Path to the iOS app icon
          "android": {
            "foregroundImage": "./assets/icon-a-foreground.png", // Path to Android foreground image
            "backgroundColor": "#001413" // Background color for Android adaptive icon
          }
        },
        {
          "name": "IconB",
          "ios": "./assets/icon-b.png",
          "android": {
            "foregroundImage": "./assets/icon-b-foreground.png",
            "backgroundColor": "#001413"
          }
        },
        {
          "name": "IconC",
          "ios": "./assets/icon-c.png",
          "android": {
            "foregroundImage": "./assets/icon-c-foreground.png",
            "backgroundColor": "#001413"
          }
        }
      ]
    ]
  ]
}

Icons

Your icons should follow the same format as your default app icon.

• Use a .png file
• Square format with resolution 1024x1024 px
• iOS
  • Without transparency layer
• Android - Adaptive icon
  • Foreground image
  • Background fill color

API Documentation

Supports Alternate Icons

A boolean value indicating whether the current device supports alternate app icons.

const supportsAlternateIcons: boolean;

Set Alternate App Icon

To set app icon to IconA, use setAlternateAppIcon("IconA"). This function takes icon name as argument.

To reset the app icon to the default pass null like setAlternateAppIcon(null).

function setAlternateAppIcon(name: string | null): Promise<string | null>;

Get App Icon Name

Retrieves the name of the currently active app icon.

function getAppIconName(): string | null;

Reset App Icon

Reset app icon to the default one.

This is just a shortcut for setAlternateAppIcon(null).

function resetAppIcon(): Promise<void>;

Development

Expo Config Plugin

npm run build plugin # Start build on save
cd example && npx expo prebuild # Execute the config plugin