app-icon-badge

To use the app-icon-badge plugin in an Expo project, add it to the plugins array in your app.config.ts (or app.json). The plugin accepts a configuration object of type AppIconBadgeOptions as its second element in the plugin array tuple.

Configuration Options

Root Options

• enabled (boolean): Enables or disables the plugin. It is recommended to set this to false for production builds to avoid badges appearing in released versions.
• badges (Array): An array of badge objects to be rendered on the app icon.

Badge Object Properties

• text (string): The text content to display on the badge (e.g., 'DEV' or a version number).
• type ('banner' | 'ribbon'): Defines the visual style of the badge. Supported values are banner or ribbon.
• color ('white' | 'black'): The color of the text. Currently, only white and black are supported.
• background (string): The background color of the badge. Must be provided in hex format (e.g., #FF0000).

import type { AppIconBadgeOptions } from 'app-icon-badge/types';

const appIconBadgeConfig: AppIconBadgeOptions = {
  enabled: true,
  badges: [
    {
      text: 'DEV',
      type: 'banner',
      color: 'white',
      background: '#FF0000',
    },
    {
      text: 'V1.0.1',
      type: 'ribbon',
    },
  ],
};

// In your app.config.ts export:
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  plugins: ['expo-router', ['app-icon-badge', appIconBadgeConfig]],
});

The loadOverlay function loads an image from a given file path and optionally replaces a specific base color (black #000000) with a new background color. This is useful for dynamically changing the color of badge overlays.

Parameters

• path (string): The file path to the image overlay.
• background (string, optional): A hex color string (e.g., #FF0000) representing the new color to apply.

Behavior

• If background is provided as a valid hex color, the function attempts to replace pixels that are close to #000000 (using Delta E color difference) with the new color.
• If background is provided but is not a valid hex color, a warning is logged to the console, and the original image is returned without changes.
• If background is not provided, the original image is returned.
• Transparent pixels are skipped during the color replacement process.

import { loadOverlay } from './load-overlay';

// Load an overlay with a specific background color
const overlay = await loadOverlay({
  path: './path/to/overlay.png',
  background: '#FF5733'
});

The withIconBadgeAsync plugin is an Expo Config Plugin used to automatically add badges to your application icons for both iOS and Android. It handles updating the main app icon, the iOS-specific icon, and the Android adaptive icon foreground image.

Behavior

• Enabled by default: If the enabled option is not provided, the plugin defaults to true.
• Icon Generation: It generates new icon files in the .expo/app-icon-badge directory and updates your app.json (or app.config.js) to point to these new files.
• Platform Support:
  • iOS: Updates the global icon and the ios.icon field.
  • Android: Updates the global icon and the android.adaptiveIcon.foregroundImage field.

Configuration Options

The plugin accepts an AppIconBadgeConfig object:

• badges: An array of Badge objects to be applied to the icon.
• enabled: A boolean determining if the plugin should run (defaults to true).

// Example usage in app.config.ts or app.json
export default { 
  expo: {
    plugins: [
      [
        'app-icon-badge/with-icon-badge-async',
        {
          enabled: true,
          badges: [
            // ... your badge configurations
          ],
        },
      ],
    ],
  },
};

The createBannerBadge function generates a banner badge image using Jimp. It overlays text onto a banner image based on the provided configuration.

Parameters

Options Object (Banner):

• text: The string to display on the banner (will be converted to uppercase).
• position: Where the banner is placed. Options are 'top' or 'bottom' (defaults to 'bottom').
• color: The font color (defaults to 'white').
• background: The background color for the banner overlay.

isAdaptiveIcon (Boolean):

• If true, the function uses an adaptive icon overlay (assets/banner-overlay-adaptive.png) and adjusts the banner height to 310. It also changes the text alignment logic to ensure text is positioned correctly relative to the adaptive icon shape.
• If false (default), it uses the standard overlay (assets/banner-overlay.png) with a height of 180 and middle-aligned text.

import { createBannerBadge } from './path-to-module';

const badge = await createBannerBadge(
  {
    text: 'v1.0.0',
    position: 'bottom',
    color: 'white',
    background: '#000000'
  },
  false
);

if (badge) {
  // badge is a Jimp instance
  await badge.writeAsync('badge.png');
}

The addBadge function is the primary entrypoint for applying one or more badges (ribbons or banners) to an icon image. It reads the source icon, composites the requested badges onto it, and saves the resulting image to a destination path.

Parameters:

• icon: The source image (path or buffer).
• dstPath: (Optional) The destination path where the resulting image will be saved. If omitted, the path is automatically generated using getResultPath.
• isAdaptiveIcon: (Optional) Boolean indicating if the icon is an adaptive icon. Defaults to false.
• badges: An array of badge configurations. Supported types are 'ribbon' and 'banner' (via createRibbonBadge and createBannerBadge).

Returns:

• A Promise that resolves to the string path of the saved result image.

import { addBadge } from 'app-icon-badge';

const resultPath = await addBadge({
  icon: './path/to/icon.png',
  dstPath: './output/icon-with-badge.png',
  isAdaptiveIcon: false,
  badges: [
    { type: 'ribbon', text: 'New' },
    { type: 'banner', text: 'Beta' }
  ],
});

console.log(`Badge added at: ${resultPath}`);

The createRibbonBadge function generates a ribbon overlay image with text, which can be used to decorate app icons. It supports positioning the ribbon on the left or right side and provides special handling for adaptive icons.

Parameters

Ribbon object

• text (string): The text to display on the ribbon.
• position ('left' | 'right'): The side of the icon where the ribbon will appear. Defaults to 'right'.
• color ('white' | 'black'): The color of the text. Defaults to 'white'.
• background (optional): The background color/image used for the ribbon overlay.

isAdaptiveIcon (boolean)

• If true, the function uses a specific overlay (assets/ribbon-overlay-adaptive.png) and different dimensions/translations optimized for adaptive icon shapes. Defaults to false.

Returns

• Returns a Promise<Jimp | null> containing the generated Jimp image instance.

import { createRibbonBadge } from './create-ribbon-badge';

const ribbon = await createRibbonBadge(
  {
    text: 'NEW',
    position: 'right',
    color: 'white',
    background: '#ff0000'
  },
  false // isAdaptiveIcon
);

if (ribbon) {
  // Use the Jimp instance (e.g., save to file)
  await ribbon.write('ribbon.png');
}

The withIconBadge plugin is an Expo Config Plugin used to automatically add badges to your application icons. It handles both standard icons and Android adaptive icons by generating new icon files in the .expo/app-icon-badge directory and updating your Expo configuration to point to these new files.

When enabled, the plugin performs the following:

1. Global Icon: If config.icon is defined, it generates a badged version at .expo/app-icon-badge/icon.png.
2. Android Adaptive Icon: If config.android.adaptiveIcon.foregroundImage is defined, it generates a badged version at .expo/app-icon-badge/foregroundImage.png with the isAdaptiveIcon flag set.
3. iOS Icon: If config.ios.icon is defined, it generates a badged version at .expo/app-icon-badge/icon.png.

If enabled is set to false in the options, the plugin will do nothing.

import { withIconBadge } from 'obytes/app-icon-badge';

export default ({ config }) => {
  return withIconBadge(config, {
    enabled: true,
    badges: [
      // your badge configurations here
    ],
  });
};