Change the homescreen icon of your NativeScript iOS app at runtime!
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo
media
publish
src
.gitignore
.travis.yml
LICENSE
README.md
tslint.json

README.md

NativeScript App Icon Changer

Build Status NPM version Downloads Twitter Follow

That's the demo app in action, switching app icons like a boss!

Installation

tns plugin add nativescript-app-icon-changer

API

requiring / importing the plugin

All examples below assume you're using TypeScript, but here's how to require the plugin with regular JS as well:

JavaScript

var AppIconChangerPlugin = require("nativescript-app-icon-changer");
var appIconChanger = new AppIconChangerPlugin.AppIconChanger();

TypeScript

import { AppIconChanger } from "nativescript-app-icon-changer";

export class MyClass {
  private appIconChanger: AppIconChanger;
  
  constructor() {
    this.appIconChanger = new AppIconChanger();
  }
}

isSupported

Only iOS 10.3 and up support this feature, so you may want to check beforehand:

this.appIconChanger.isSupported().then(
    supported => console.log(`Supported: ${supported}`));

changeIcon

To be able to switch to a different icon add it to App_Resources/iOS and App_Resources/iOS/Info.plist as explained below and pass iconName to changeIcon.

To reset to the default icon, use iconName: null.

Note 1: iOS will notify the user the icon changed, but this plugin allows you to suppress that message (it's the default even). It's probably not what Apple would like you to do, but no apps have been disapproved with suppression enabled.

Note 2: Changing the app icon is only allowed when the app is in the foreground, so forget about that weather app which silently updates its app icon.

this.appIconChanger.changeIcon({
  iconName: "icon-blue", // or null to reset to the default
  suppressUserNotification: true
});

currentAlternateIcon

Want to know whether or not the app currently has an alternate icon configured? And if so, what its name is? Then use this:

// synchronous
const currentAppIconName: string = this.appIconChanger.currentAlternateIcon();

Preparing your app for icon switching

Apple doesn't allow switching to arbitrary icons, so they must be bundled with your app before releasing the app to the store.

Add the icons you'd like your users to be able to switch to for all relevant resolutions as usual.

Note that you DON'T NEED to provide all those resolutions; you could get away with adding just the largest resolution and refer to it in the plist file. iOS will scale it down to other resolutions for you.

Then reference those icons in App_Resources/iOS/Info.plist as well:

<plist>
<dict>

  <!-- Add or merge this bit -->
  <key>CFBundleIcons</key>
  <dict>
    <key>CFBundleAlternateIcons</key>
    <dict>
      <!-- The name you use in code -->
      <key>icon-blue</key>
      <dict>
        <key>UIPrerenderedIcon</key>
        <true/>
        <key>CFBundleIconFiles</key>
        <array>
          <!-- The actual filenames. Don't list the @2x/@3x files here -->
          <string>icon-blue-57</string>
          <string>icon-blue-60</string>
          <string>icon-blue-72</string>
          <string>icon-blue-76</string>
        </array>
      </dict>
    </dict>
  </dict>

</dict>
</plist>

Need iPad support as well? Just duplicate that plist config and change <key>CFBundleIcons</key> to <key>CFBundleIcons~ipad</key>.

Want to see this configured in an actual project? Look at the demo app to see the gory details.