# Icons & launch screens

> Where the app icon and launch screen come from on each platform, and what sizes to supply.

- Source: https://titaniumsdk.com/docs/build/ui/icons-and-launch-screens
- Written for Titanium SDK 13.4.0 and later.
- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.

---

The two platforms do not share an icon, despite `DefaultIcon.png` sitting at
the project root looking like they might. iOS generates its whole icon set from
that file. **Android never reads it.**

| | iOS | Android |
| --- | --- | --- |
| Source | `DefaultIcon.png` at the project root | `platform/android/res/mipmap-*/` |
| Generated by Titanium | Yes, every size | No, you supply the set |
| Named in `tiapp.xml` | No | `android:icon="@mipmap/ic_launcher"` |

`ti create` writes both, so a new project has a working icon on each platform
before you touch anything.

## iOS

Put a square PNG at `DefaultIcon.png` in the project root and Titanium resizes
it into the app icon set at build time. **1024x1024** is the size to supply,
because that is what the App Store listing needs and every other size is
reduced from it.

Alpha is flattened for the icon, so a transparent background becomes white.
Design on an opaque background rather than being surprised.

To differ from Android, add `DefaultIcon-ios.png`. It takes precedence over the
shared file.

### Dark and tinted appearances

iOS 18 asks for three appearances. Add them beside the default one and
Titanium picks them up:

| File | Appearance |
| ---- | ---------- |
| `DefaultIcon.png` | Light, and the fallback for the others |
| `DefaultIcon-Dark.png` | Dark mode |
| `DefaultIcon-Tinted.png` | Tinted mode |

Newer Xcode toolchains also accept an Icon Composer document at
`DefaultIcon-ios.icon`, which carries every size and appearance itself. When
one is present Titanium renders from it and skips generating an icon set.

### Launch screens

Titanium builds a launch screen storyboard by default, controlled in
`tiapp.xml`:

```xml
<ios>
  <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
</ios>
```

With it on, the launch image is generated by centring your icon on a plain
background, which is why a new project launches to its own icon without you
supplying anything. Turn it off and iOS falls back to the fixed-size
`Default-*.png` images in `Resources/iphone/`, which is the pre-storyboard
approach and means one file per device size.

Leave the storyboard on unless you have a reason. Apple has required one for
new App Store submissions since 2020.

## Android

Android uses adaptive icons: a foreground layer, a background layer, and a
monochrome layer for themed icons, composited by the launcher into whatever
shape the device uses. `ti create` writes all three at every density:

```
platform/android/res/
  mipmap-anydpi-v26/ic_launcher.xml     which layers to composite
  mipmap-mdpi/      ic_launcher_foreground.png  48px
  mipmap-hdpi/      ...                         72px
  mipmap-xhdpi/     ...                         96px
  mipmap-xxhdpi/    ...                        144px
  mipmap-xxxhdpi/   ...                        192px
```

Replace the PNGs at every density. The launcher crops the outer edge of an
adaptive icon to whatever shape it wants, so keep anything that must stay
visible inside the middle two-thirds.

In an Alloy project these live under `app/platform/android/res/`, because
`alloy new` moved `platform/` there. See
[project structure](https://titaniumsdk.com/docs/build/project-structure.md).

### Splash screen

Android's splash is a theme, not an image set. It is generated from the same
launcher icon, so replacing the icon replaces what shows on launch.

## Changing the name under the icon

That is `<name>` in `tiapp.xml`, not an icon setting. Both platforms read it
from there.

## Next

[Platform conventions](https://titaniumsdk.com/docs/build/ui/platform-conventions.md) covers the places
iOS and Android expect different things of an app.