App Icon

Let people choose a bundled alternate iOS Home Screen icon

One.AppIcon reads and changes the icon iOS displays for your app. The icon images must be bundled into the binary before calling setIcon.

With One prebuild, configure a primary icon and named alternates in native.app:

native: {
  app: {
    // ...name and platform IDs
    icon: { source: 'assets/icon.svg', backgroundColor: '#154a9c' },
    ios: {
      // ...bundleId
      alternateIcons: {
        Blue: { source: 'assets/icon-blue.svg', backgroundColor: '#154a9c' },
        Orange: { source: 'assets/icon-orange.svg', backgroundColor: '#d95918' },
      },
    },
  },
}

Each source must be square and at least 1024 pixels wide. One prebuild creates the iOS icon sets and selects them in Xcode’s Alternate App Icon Sets build setting. The names in alternateIcons are the names passed to setIcon. After changing icon configuration, rebuild the native app. An over-the-air JavaScript update cannot add icon images to an installed binary.

import { One } from 'one'

if (await One.AppIcon.isSupported()) {
  const current = await One.AppIcon.getCurrentName()
  // undefined means the primary icon is showing.
  if (current !== 'Orange') await One.AppIcon.setIcon('Orange')
  // Passing no name restores the primary icon.
  await One.AppIcon.setIcon()
}

iOS displays a system alert when the icon changes. Call setIcon from a user action while the app is active. getCurrentName returns the installed icon’s name, or undefined for the primary icon. Repeating the current selection returns without another alert. An unknown name rejects with E_APP_ICON_INPUT; unavailable icon switching, an inactive app, concurrent changes, and system failures reject with E_APP_ICON_UNAVAILABLE, E_APP_ICON_INACTIVE, E_APP_ICON_BUSY, and E_APP_ICON_CHANGE respectively. Alternate icons are implemented on iOS and Android. On Android the icon set is the app manifest’s manually supplied activity-alias entries: the icon name is the alias component’s simple name, isSupported() is true only when at least one alias exists, and getCurrentName() returns undefined for the primary icon. Without aliases isSupported() resolves false, getCurrentName() resolves an empty string, and setIcon() does nothing on Android and web.

For an Expo prebuild, add the icon sets to the Xcode asset catalog and set Xcode’s Alternate App Icon Sets build setting; the runtime API uses the same names. See Apple’s alternate icon setup guide.