# SplashScreen

Artifact: [androidx.core:core-splashscreen](https://developer.android.com/jetpack/androidx/releases/core) [View Source](https://cs.android.com/search?q=file:androidx/core/splashscreen/SplashScreen.kt+class:androidx.core.splashscreen.SplashScreen) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/core#1.0.0)

*** ** * ** ***

<br />

```
class SplashScreen
```

<br />

*** ** * ** ***

Provides control over the splash screen once the application is started.

On API 31+ (Android 12+) this class calls the platform methods.

Prior API 31, the platform behavior is replicated with the exception of the Animated Vector Drawable support on the launch screen.

# Usage of the `core-splashscreen` library:

To replicate the splash screen behavior from Android 12 on older APIs the following steps need to be taken:

1. Create a new Theme (e.g `Theme.App.Starting`) and set its parent to `Theme.SplashScreen` or `Theme.SplashScreen.IconBackground`

2. In your manifest, set the `theme` attribute of the whole `<application>` or just the starting `<activity>` to `Theme.App.Starting`

3. In the `onCreate` method the starting activity, call `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen#(android.app.Activity).installSplashScreen()` just before `super.onCreate()`. You also need to make sure that `postSplashScreenTheme` is set to the application's theme. Alternatively, this call can be replaced by Activity#setTheme if a `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen` instance isn't needed.

## Themes

The library provides two themes: `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/R.style#Theme_SplashScreen()` and `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/R.style#Theme_SplashScreen_IconBackground()`. If you wish to display a background right under your icon, the later needs to be used. This ensure that the scale and masking of the icon are similar to the Android 12 Splash Screen.

`windowSplashScreenAnimatedIcon`: The splash screen icon. On API 31+ it can be an animated vector drawable.

`windowSplashScreenAnimationDuration`: Duration of the Animated Icon Animation. The value needs to be \> 0 if the icon is animated.

**Note:** This has no impact on the time during which the splash screen is displayed and is only used in `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreenViewProvider#iconAnimationDurationMillis()`. If you need to display the splash screen for a longer time, you can use `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen#setKeepOnScreenCondition(androidx.core.splashscreen.SplashScreen.KeepOnScreenCondition)`

`windowSplashScreenIconBackgroundColor`: *To be used in with `Theme.SplashScreen.IconBackground`*. Sets a background color under the splash screen icon.

`windowSplashScreenBackground`: Background color of the splash screen. Defaults to the theme's `?attr/colorBackground`.

`postSplashScreenTheme`\* Theme to apply to the Activity when `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen#(android.app.Activity).installSplashScreen()` is called.

**Known incompatibilities:**

- On API \< 31, `windowSplashScreenAnimatedIcon` cannot be animated. If you want to provide an animated icon for API 31+ and a still icon for API \<31, you can do so by overriding the still icon with an animated vector drawable in `res/drawable-v31`.

- On API \< 31, if the value of `windowSplashScreenAnimatedIcon` is an [adaptive icon](http://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive) , it will be cropped and scaled. The workaround is to respectively assign `windowSplashScreenAnimatedIcon` and `windowSplashScreenIconBackgroundColor` to the values of the adaptive icon `foreground` and `background`.

- On API 21-22, The icon isn't displayed until the application starts, only the background is visible.

# Design

The splash screen icon uses the same specifications as [Adaptive Icons](https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive) . This means that the icon needs to fit within a circle whose diameter is 2/3 the size of the icon. The actual values don't really matter if you use a vector icon.

## Specs

- With icon background (`Theme.SplashScreen.IconBackground`)

  - Image Size: 240x240 dp

  - Inner Circle diameter: 160 dp

- Without icon background (`Theme.SplashScreen`) + Image size: 288x288 dp + Inner circle diameter: 192 dp

*Example:* if the full size of the image is 300dp\*300dp, the icon needs to fit within a circle with a diameter of 200dp. Everything outside the circle will be invisible (masked).

## Summary

| ### Nested types |
|---|
| `fun interface https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen.KeepOnScreenCondition` Condition evaluated to check if the splash screen should remain on screen |
| `fun interface https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener` Listener to be passed in `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen#setOnExitAnimationListener(androidx.core.splashscreen.SplashScreen.OnExitAnimationListener)`. |

| ### Public companion functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen` | `https://developer.android.com/reference/android/app/Activity.html.https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen#(android.app.Activity).installSplashScreen()()` Creates a `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen` instance associated with this `https://developer.android.com/reference/android/app/Activity.html` and handles setting the theme to `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/R.attr#postSplashScreenTheme()`. |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen#setKeepOnScreenCondition(androidx.core.splashscreen.SplashScreen.KeepOnScreenCondition)(condition: https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen.KeepOnScreenCondition)` Sets the condition to keep the splash screen visible. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen#setOnExitAnimationListener(androidx.core.splashscreen.SplashScreen.OnExitAnimationListener)( listener: https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener )` Sets a listener that will be called when the splashscreen is ready to be removed. |

## Public companion functions

### Activity.installSplashScreen

Artifact: [androidx.core:core-splashscreen](https://developer.android.com/jetpack/androidx/releases/core) [View Source](https://cs.android.com/search?q=file:androidx/core/splashscreen/SplashScreen.kt+function:installSplashScreen) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/core#1.0.0)

```
fun Activity.installSplashScreen(): SplashScreen
```

Creates a `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen` instance associated with this `https://developer.android.com/reference/android/app/Activity.html` and handles setting the theme to `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/R.attr#postSplashScreenTheme()`.

This needs to be called before `https://developer.android.com/reference/android/app/Activity.html#setContentView(android.view.View)` or other view operations on the root view (e.g setting flags).

Alternatively, if a `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen` instance is not required, the theme can manually be set using `https://developer.android.com/reference/android/app/Activity.html#setTheme(int)`.

## Public functions

### setKeepOnScreenCondition

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/core#1.0.0)

```
fun setKeepOnScreenCondition(condition: SplashScreen.KeepOnScreenCondition): Unit
```

Sets the condition to keep the splash screen visible.

The splash will stay visible until the condition isn't met anymore. The condition is evaluated before each request to draw the application, so it needs to be fast to avoid blocking the UI.

| Parameters |
|---|---|
| `condition: https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen.KeepOnScreenCondition` | The condition evaluated to decide whether to keep the splash screen on screen |

### setOnExitAnimationListener

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/core#1.0.0)

```
fun setOnExitAnimationListener(
    listener: SplashScreen.OnExitAnimationListener
): Unit
```

Sets a listener that will be called when the splashscreen is ready to be removed.

If a listener is set, the splashscreen won't be automatically removed and the application needs to manually call `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreenViewProvider#remove()`.

IF no listener is set, the splashscreen will be automatically removed once the app is ready to draw.

The listener will be called on the ui thread.

| Parameters |
|---|---|
| `listener: https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener` | The `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener` that will be called when the splash screen is ready to be dismissed. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen#setKeepOnScreenCondition(androidx.core.splashscreen.SplashScreen.KeepOnScreenCondition)` |   |
| `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener` |   |
| `https://developer.android.com/reference/kotlin/androidx/core/splashscreen/SplashScreenViewProvider` |   |