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, follow PascalCase convention
          ios: {
            light: './assets/icon-a.png',
            dark: './assets/icon-a-dark.png',
            tinted: './assets/icon-a-tinted.png',
          }, // Path to the iOS app icons or if you do not want to use the variants enter directly the path
          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', // Without variants,
          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',
          },
        },
      ],
    ],
  ],
}

Note: Icon names are automatically converted to PascalCase. For example, "icon-a" becomes "IconA".

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

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