Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pchalupa/expo-alternate-app-icons
Provides functions that let you change the app icon.
https://github.com/pchalupa/expo-alternate-app-icons
expo react-native
Last synced: 13 days ago
JSON representation
Provides functions that let you change the app icon.
- Host: GitHub
- URL: https://github.com/pchalupa/expo-alternate-app-icons
- Owner: pchalupa
- License: mit
- Created: 2023-10-02T19:20:07.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-08T11:27:34.000Z (7 months ago)
- Last Synced: 2024-04-08T12:36:45.855Z (7 months ago)
- Topics: expo, react-native
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/expo-alternate-app-icons
- Size: 6.53 MB
- Stars: 12
- Watchers: 2
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 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:
```sh
npx expo install expo-alternate-app-icons
```
> Ensure your project is running Expo SDK 44+.
## 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](https://docs.expo.dev/versions/latest/config/app/).
2. The second item in the array accepts an array with details about your alternate icons.
3. [Prebuild](https://docs.expo.dev/workflow/prebuild/) a project using `npx expo prebuild --clean` to apply the plugin changes.
```json
// app.json
{
// ...
"plugins": [
// ...
[
"expo-alternate-app-icons",
[
{
"name": "IconA", // The name of the alternate icon
"ios": "./assets/icon-a.png", // Path to the iOS app icon
"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",
"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"
}
}
]
]
]
}
```
### Icons
Your icons should follow the same format as your [default app icon](https://docs.expo.dev/develop/user-interface/splash-screen-and-app-icon/#export-the-icon-image-as-a-png).
- 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.
```ts
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)`.
```ts
function setAlternateAppIcon(name: string | null): Promise;
```
#### Get App Icon Name
Retrieves the name of the currently active app icon.
```ts
function getAppIconName(): string | null;
```
#### Reset App Icon
Reset app icon to the default one.
> This is just a shortcut for `setAlternateAppIcon(null)`.
```ts
function resetAppIcon(): Promise;
```
## Development
### Expo Config Plugin
```shell
npm run build plugin # Start build on save
cd example && npx expo prebuild # Execute the config plugin
```