expo-app-icon 1.2.0 → 1.4.0

package/README.md

@@ -3,7 +3,7 @@
 </div>
   
 # Expo App Icon
-Programmatically change your app's icon at runtime in Expo, with proper Android adaptive-icon support.
+Programmatically change your app's icon at runtime in Expo.
 
 ## Install
 
@@ -31,18 +31,21 @@ Add the plugin to your `app.json` config and declare your icons. Each icon is ju
 }
 ```
 
-The same image is used for both platforms. To use a different image per platform, pass an object instead:
+The same image is used for both platforms. For per-platform images, use the object form:
 
 ```json
 {
   "red": "./assets/icons/red.png",
-  "blue": {
-    "ios": "./assets/icons/blue-ios.png",
-    "android": "./assets/icons/blue-android.png"
+  "blue": { "image": "./assets/icons/blue.png" },
+  "split": {
+    "ios": "./assets/icons/split-ios.png",
+    "android": "./assets/icons/split-android.png"
   }
 }
 ```
 
+- `image` sets both platforms; `ios` / `android` override it per platform.
+
 Then create a new build (the plugin runs during prebuild):
 
 ```sh
@@ -51,15 +54,34 @@ npx expo prebuild --clean
 
 ## Usage
 
+Switch icons at runtime with the `useAppIcon` hook — no per-app persistence needed (the native module is the source of truth). `IconName` is typed to your configured keys:
+
+```tsx
+import { useAppIcon, type IconName } from "expo-app-icon";
+
+const ICONS: IconName[] = ["red", "blue"];
+
+function IconPicker() {
+  const { icon, setIcon, isDefault } = useAppIcon();
+
+  return ICONS.map((name) => (
+    <Pressable key={name} onPress={() => setIcon(name)}>
+      <Text>{name}{icon === name ? " ✓" : ""}</Text>
+    </Pressable>
+  ));
+}
+```
+
+- `icon` — the current icon key, or `null` for the default.
+- `setIcon(name | null)` — switch icons; pass `null` to reset to the default. (The iOS timing fix is built in.)
+- `isDefault` / `isSupported` — handy flags (`isSupported` is `false` on web).
+
+Or call the underlying functions directly:
+
 ```ts
 import { getAppIcon, setAppIcon } from "expo-app-icon";
 
-// Get the name of the current icon ("DEFAULT" when none is set)
-const current = getAppIcon();
-
-// Switch to one of your configured icons by key
+const current = getAppIcon(); // icon name, or "DEFAULT"
 setAppIcon("red");
-
-// Reset back to the default icon
-setAppIcon(null);
+setAppIcon(null); // reset to default
 ```

package/build/index.d.ts

@@ -1,4 +1,6 @@
 import type { DynamicAppIconRegistry } from "./types";
+export { useAppIcon } from "./useAppIcon";
+export type { UseAppIcon } from "./useAppIcon";
 /**
  * Union of the icon keys declared in the plugin config (widened to string when none).
  */

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAGtD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,YAAY,EAAG,SAAkB,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,QAAQ,GAAG,IAAI,GACpB,QAAQ,GAAG,OAAO,YAAY,GAAG,KAAK,CAExC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,QAAQ,GAAG,OAAO,YAAY,CAE3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,YAAY,EAAG,SAAkB,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,QAAQ,GAAG,IAAI,GACpB,QAAQ,GAAG,OAAO,YAAY,GAAG,KAAK,CAExC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,QAAQ,GAAG,OAAO,YAAY,CAE3D"}

package/build/index.js

@@ -1,4 +1,5 @@
 import NativeAppIcon from "./ExpoAppIconChangerModule";
+export { useAppIcon } from "./useAppIcon";
 /**
  * Value reported / accepted for the project's default launcher icon.
  */

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,aAAa,MAAM,4BAA4B,CAAC;AAOvD;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAkB,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,IAAqB;IAErB,OAAO,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,aAAa,CAAC,UAAU,EAAE,CAAC;AACpC,CAAC","sourcesContent":["import type { DynamicAppIconRegistry } from \"./types\";\nimport NativeAppIcon from \"./ExpoAppIconChangerModule\";\n\n/**\n * Union of the icon keys declared in the plugin config (widened to string when none).\n */\nexport type IconName = DynamicAppIconRegistry[\"IconName\"];\n\n/**\n * Value reported / accepted for the project's default launcher icon.\n */\nexport const DEFAULT_ICON = \"DEFAULT\" as const;\n\n/**\n * Switch the launcher icon at runtime.\n *\n * @param name A configured icon key, or `null` to reset to the default icon.\n * @returns The applied icon name, `\"DEFAULT\"`, or `false` if unsupported.\n */\nexport function setAppIcon(\n  name: IconName | null\n): IconName | typeof DEFAULT_ICON | false {\n  return NativeAppIcon.setAppIcon(name);\n}\n\n/**\n * Get the currently active icon name, or `\"DEFAULT\"` when none is set.\n */\nexport function getAppIcon(): IconName | typeof DEFAULT_ICON {\n  return NativeAppIcon.getAppIcon();\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,aAAa,MAAM,4BAA4B,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAQ1C;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAkB,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,IAAqB;IAErB,OAAO,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,aAAa,CAAC,UAAU,EAAE,CAAC;AACpC,CAAC","sourcesContent":["import type { DynamicAppIconRegistry } from \"./types\";\nimport NativeAppIcon from \"./ExpoAppIconChangerModule\";\n\nexport { useAppIcon } from \"./useAppIcon\";\nexport type { UseAppIcon } from \"./useAppIcon\";\n\n/**\n * Union of the icon keys declared in the plugin config (widened to string when none).\n */\nexport type IconName = DynamicAppIconRegistry[\"IconName\"];\n\n/**\n * Value reported / accepted for the project's default launcher icon.\n */\nexport const DEFAULT_ICON = \"DEFAULT\" as const;\n\n/**\n * Switch the launcher icon at runtime.\n *\n * @param name A configured icon key, or `null` to reset to the default icon.\n * @returns The applied icon name, `\"DEFAULT\"`, or `false` if unsupported.\n */\nexport function setAppIcon(\n  name: IconName | null\n): IconName | typeof DEFAULT_ICON | false {\n  return NativeAppIcon.setAppIcon(name);\n}\n\n/**\n * Get the currently active icon name, or `\"DEFAULT\"` when none is set.\n */\nexport function getAppIcon(): IconName | typeof DEFAULT_ICON {\n  return NativeAppIcon.getAppIcon();\n}\n"]}

package/build/index.web.d.ts

@@ -1,6 +1,12 @@
 import type { DynamicAppIconRegistry } from "./types";
+import type { UseAppIcon } from "./useAppIcon";
+export type { UseAppIcon } from "./useAppIcon";
 export type IconName = DynamicAppIconRegistry["IconName"];
 export declare const DEFAULT_ICON: "DEFAULT";
+/**
+ * Web has no launcher icon; the hook reports an unsupported, default state.
+ */
+export declare function useAppIcon(): UseAppIcon;
 /**
  * Web has no launcher icon; this is a no-op that reports failure.
  */

package/build/index.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../src/index.web.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEtD,MAAM,MAAM,QAAQ,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;AAE1D,eAAO,MAAM,YAAY,EAAG,SAAkB,CAAC;AAE/C;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,QAAQ,GAAG,IAAI,GACrB,QAAQ,GAAG,OAAO,YAAY,GAAG,KAAK,CAGxC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,QAAQ,GAAG,OAAO,YAAY,CAG3D"}
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../src/index.web.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;AAE1D,eAAO,MAAM,YAAY,EAAG,SAAkB,CAAC;AAE/C;;GAEG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAEvC;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,QAAQ,GAAG,IAAI,GACrB,QAAQ,GAAG,OAAO,YAAY,GAAG,KAAK,CAGxC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,QAAQ,GAAG,OAAO,YAAY,CAG3D"}

package/build/index.web.js

@@ -1,4 +1,10 @@
 export const DEFAULT_ICON = "DEFAULT";
+/**
+ * Web has no launcher icon; the hook reports an unsupported, default state.
+ */
+export function useAppIcon() {
+    return { icon: null, setIcon: () => { }, isDefault: true, isSupported: false };
+}
 /**
  * Web has no launcher icon; this is a no-op that reports failure.
  */

package/build/index.web.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.web.js","sourceRoot":"","sources":["../src/index.web.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,YAAY,GAAG,SAAkB,CAAC;AAE/C;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,KAAsB;IAEtB,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACpD,OAAO,YAAY,CAAC;AACtB,CAAC","sourcesContent":["import type { DynamicAppIconRegistry } from \"./types\";\n\nexport type IconName = DynamicAppIconRegistry[\"IconName\"];\n\nexport const DEFAULT_ICON = \"DEFAULT\" as const;\n\n/**\n * Web has no launcher icon; this is a no-op that reports failure.\n */\nexport function setAppIcon(\n  _name: IconName | null\n): IconName | typeof DEFAULT_ICON | false {\n  console.error(\"setAppIcon is not supported on web\");\n  return false;\n}\n\n/**\n * Web has no launcher icon; always reports the default.\n */\nexport function getAppIcon(): IconName | typeof DEFAULT_ICON {\n  console.error(\"getAppIcon is not supported on web\");\n  return DEFAULT_ICON;\n}\n"]}
+{"version":3,"file":"index.web.js","sourceRoot":"","sources":["../src/index.web.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,YAAY,GAAG,SAAkB,CAAC;AAE/C;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AAChF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,KAAsB;IAEtB,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACpD,OAAO,YAAY,CAAC;AACtB,CAAC","sourcesContent":["import type { DynamicAppIconRegistry } from \"./types\";\nimport type { UseAppIcon } from \"./useAppIcon\";\n\nexport type { UseAppIcon } from \"./useAppIcon\";\n\nexport type IconName = DynamicAppIconRegistry[\"IconName\"];\n\nexport const DEFAULT_ICON = \"DEFAULT\" as const;\n\n/**\n * Web has no launcher icon; the hook reports an unsupported, default state.\n */\nexport function useAppIcon(): UseAppIcon {\n  return { icon: null, setIcon: () => {}, isDefault: true, isSupported: false };\n}\n\n/**\n * Web has no launcher icon; this is a no-op that reports failure.\n */\nexport function setAppIcon(\n  _name: IconName | null\n): IconName | typeof DEFAULT_ICON | false {\n  console.error(\"setAppIcon is not supported on web\");\n  return false;\n}\n\n/**\n * Web has no launcher icon; always reports the default.\n */\nexport function getAppIcon(): IconName | typeof DEFAULT_ICON {\n  console.error(\"getAppIcon is not supported on web\");\n  return DEFAULT_ICON;\n}\n"]}

package/build/useAppIcon.d.ts

@@ -0,0 +1,20 @@
+import type { DynamicAppIconRegistry } from "./types";
+type IconName = DynamicAppIconRegistry["IconName"];
+export type UseAppIcon = {
+    /** Current icon; `null` means the default icon. */
+    icon: IconName | null;
+    /** Set the icon, or pass `null` to reset to the default. */
+    setIcon: (name: IconName | null) => void;
+    /** Whether the current icon is the default. */
+    isDefault: boolean;
+    /** Whether changing the icon is supported on this platform. */
+    isSupported: boolean;
+};
+/**
+ * React hook for the app's launcher icon. The native module is the source of
+ * truth (the value survives the app restart an Android change triggers), so no
+ * extra persistence is needed.
+ */
+export declare function useAppIcon(): UseAppIcon;
+export {};
+//# sourceMappingURL=useAppIcon.d.ts.map

package/build/useAppIcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAppIcon.d.ts","sourceRoot":"","sources":["../src/useAppIcon.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEtD,KAAK,QAAQ,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;AAWnD,MAAM,MAAM,UAAU,GAAG;IACvB,mDAAmD;IACnD,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,4DAA4D;IAC5D,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,KAAK,IAAI,CAAC;IACzC,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAuBvC"}

package/build/useAppIcon.js

@@ -0,0 +1,40 @@
+import { useCallback, useState } from "react";
+import NativeAppIcon from "./ExpoAppIconChangerModule";
+/**
+ * Read the current icon from the native module, normalising the default
+ * (`"DEFAULT"`) to `null`.
+ */
+function readCurrentIcon() {
+    const current = NativeAppIcon.getAppIcon();
+    return current === "DEFAULT" ? null : current;
+}
+/**
+ * React hook for the app's launcher icon. The native module is the source of
+ * truth (the value survives the app restart an Android change triggers), so no
+ * extra persistence is needed.
+ */
+export function useAppIcon() {
+    const [icon, setIconState] = useState(() => {
+        try {
+            return readCurrentIcon();
+        }
+        catch {
+            return null;
+        }
+    });
+    const setIcon = useCallback((name) => {
+        // Defer so any parent re-render (e.g. a menu closing) settles before the
+        // native call, which can present a system alert / restart the app.
+        setTimeout(() => {
+            try {
+                NativeAppIcon.setAppIcon(name);
+                setIconState(name);
+            }
+            catch (error) {
+                console.error("Failed to set app icon:", error);
+            }
+        }, 0);
+    }, []);
+    return { icon, setIcon, isDefault: icon === null, isSupported: true };
+}
+//# sourceMappingURL=useAppIcon.js.map

package/build/useAppIcon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAppIcon.js","sourceRoot":"","sources":["../src/useAppIcon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE9C,OAAO,aAAa,MAAM,4BAA4B,CAAC;AAKvD;;;GAGG;AACH,SAAS,eAAe;IACtB,MAAM,OAAO,GAAG,aAAa,CAAC,UAAU,EAAE,CAAC;IAC3C,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,OAAoB,CAAC;AAC9D,CAAC;AAaD;;;;GAIG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAkB,GAAG,EAAE;QAC1D,IAAI,CAAC;YACH,OAAO,eAAe,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,IAAqB,EAAE,EAAE;QACpD,yEAAyE;QACzE,mEAAmE;QACnE,UAAU,CAAC,GAAG,EAAE;YACd,IAAI,CAAC;gBACH,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBAC/B,YAAY,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;YAClD,CAAC;QACH,CAAC,EAAE,CAAC,CAAC,CAAC;IACR,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,KAAK,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AACxE,CAAC","sourcesContent":["import { useCallback, useState } from \"react\";\n\nimport NativeAppIcon from \"./ExpoAppIconChangerModule\";\nimport type { DynamicAppIconRegistry } from \"./types\";\n\ntype IconName = DynamicAppIconRegistry[\"IconName\"];\n\n/**\n * Read the current icon from the native module, normalising the default\n * (`\"DEFAULT\"`) to `null`.\n */\nfunction readCurrentIcon(): IconName | null {\n  const current = NativeAppIcon.getAppIcon();\n  return current === \"DEFAULT\" ? null : (current as IconName);\n}\n\nexport type UseAppIcon = {\n  /** Current icon; `null` means the default icon. */\n  icon: IconName | null;\n  /** Set the icon, or pass `null` to reset to the default. */\n  setIcon: (name: IconName | null) => void;\n  /** Whether the current icon is the default. */\n  isDefault: boolean;\n  /** Whether changing the icon is supported on this platform. */\n  isSupported: boolean;\n};\n\n/**\n * React hook for the app's launcher icon. The native module is the source of\n * truth (the value survives the app restart an Android change triggers), so no\n * extra persistence is needed.\n */\nexport function useAppIcon(): UseAppIcon {\n  const [icon, setIconState] = useState<IconName | null>(() => {\n    try {\n      return readCurrentIcon();\n    } catch {\n      return null;\n    }\n  });\n\n  const setIcon = useCallback((name: IconName | null) => {\n    // Defer so any parent re-render (e.g. a menu closing) settles before the\n    // native call, which can present a system alert / restart the app.\n    setTimeout(() => {\n      try {\n        NativeAppIcon.setAppIcon(name);\n        setIconState(name);\n      } catch (error) {\n        console.error(\"Failed to set app icon:\", error);\n      }\n    }, 0);\n  }, []);\n\n  return { icon, setIcon, isDefault: icon === null, isSupported: true };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-icon",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Programmatically change the app icon at runtime in Expo, with Android adaptive-icon support.",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/plugin/build/icons.d.ts

@@ -2,7 +2,8 @@ import type { AppleIconVariant, IconConfig, IconPluginInput, IconSet, ResolvedIc
 /**
  * Coerce whatever the user placed in app config into a normalized icon map.
  * A bare array of image paths is expanded to keyed entries that share the same
- * image for both platforms.
+ * image for both platforms. For the object form, the `image` convenience is
+ * expanded to `ios`/`android` (which override it).
  */
 export declare function normalizeIconSet(input: IconPluginInput): IconSet;
 /**

package/plugin/build/icons.js

@@ -14,7 +14,8 @@ const APPLE_ICON_BLUEPRINTS = [
 /**
  * Coerce whatever the user placed in app config into a normalized icon map.
  * A bare array of image paths is expanded to keyed entries that share the same
- * image for both platforms.
+ * image for both platforms. For the object form, the `image` convenience is
+ * expanded to `ios`/`android` (which override it).
  */
 function normalizeIconSet(input) {
     if (Array.isArray(input)) {
@@ -25,11 +26,18 @@ function normalizeIconSet(input) {
     }
     if (!input)
         return {};
-    return Object.fromEntries(Object.entries(input).map(([key, value]) => [
-        key,
+    return Object.fromEntries(Object.entries(input).map(([key, value]) => {
         // String shorthand: one image path used for both platforms.
-        typeof value === "string" ? { ios: value, android: value } : value,
-    ]));
+        if (typeof value === "string") {
+            return [key, { ios: value, android: value }];
+        }
+        const { image, ios, android } = value;
+        const config = {
+            ios: ios ?? image,
+            android: android ?? image,
+        };
+        return [key, config];
+    }));
 }
 /**
  * Build the list of Apple icon variants to emit for the given tablet support.

package/plugin/build/index.js

@@ -26,13 +26,14 @@ const withDynamicIcon = (config, input) => {
     return config;
 };
 /**
- * Rewrite the shipped `IconName` union in `build/types.d.ts` to the configured
- * icon keys, so `getAppIcon()` / `setAppIcon()` are typed to this project.
+ * Rewrite the `IconName` union in the shipped `build/types.d.ts` so
+ * `getAppIcon()` / `setAppIcon()` / `useAppIcon()` are typed to the configured
+ * keys. The types file only exists in a built package, so the write is
+ * best-effort.
  */
 function withTypedIconNames(config, icons) {
-    const union = Object.keys(icons)
-        .map((name) => `"${name}"`)
-        .join(" | ") || "string";
+    const names = Object.keys(icons);
+    const union = names.map((name) => `"${name}"`).join(" | ") || "string";
     const typesFile = path_1.default.join(PACKAGE_ROOT, "build", "types.d.ts");
     try {
         const current = fs_1.default.readFileSync(typesFile, "utf8");

package/plugin/build/types.d.ts

@@ -1,5 +1,6 @@
 /**
- * A single icon entry as declared in the plugin config.
+ * A normalized icon entry as used everywhere internally (the `image`
+ * convenience has been expanded to `ios`/`android`).
  */
 export type IconConfig = {
     /**
@@ -16,11 +17,19 @@ export type IconConfig = {
  * fully-resolved object form).
  */
 export type IconSet = Record<string, IconConfig>;
+/**
+ * The object form a consumer may declare. Adds `image` as a convenience that
+ * sets both platforms (`ios`/`android` override it when present).
+ */
+export type IconInputObject = IconConfig & {
+    /** Single image used for both platforms (shorthand for ios + android). */
+    image?: string;
+};
 /**
  * An icon as declared by the user: either a single image path used for both
- * platforms (`"red": "./assets/red.png"`) or the explicit per-platform object.
+ * platforms (`"red": "./assets/red.png"`) or the explicit object form.
  */
-export type IconInput = string | IconConfig;
+export type IconInput = string | IconInputObject;
 /**
  * What the plugin accepts from the app config: a keyed map (string shorthand or
  * object per icon), a bare list of image paths, or nothing.