# 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 />

```
public final 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/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/androidx/core/splashscreen/SplashScreen` instance isn't needed.

## Themes

The library provides two themes: `https://developer.android.com/reference/androidx/core/splashscreen/R.style#Theme_SplashScreen()` and `https://developer.android.com/reference/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/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/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/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 |
|---|
| `public fun interface https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen.KeepOnScreenCondition` Condition evaluated to check if the splash screen should remain on screen |
| `public fun interface https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener` Listener to be passed in `https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen#setOnExitAnimationListener(androidx.core.splashscreen.SplashScreen.OnExitAnimationListener)`. |

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen` | `https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen#(android.app.Activity).installSplashScreen()(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/app/Activity.html receiver)` Creates a `https://developer.android.com/reference/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/androidx/core/splashscreen/R.attr#postSplashScreenTheme()`. |
| `final void` | `https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen#setKeepOnScreenCondition(androidx.core.splashscreen.SplashScreen.KeepOnScreenCondition)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen.KeepOnScreenCondition condition )` Sets the condition to keep the splash screen visible. |
| `final void` | `https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen#setOnExitAnimationListener(androidx.core.splashscreen.SplashScreen.OnExitAnimationListener)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener listener )` Sets a listener that will be called when the splashscreen is ready to be removed. |

## Public methods

### installSplashScreen

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

```
public static final @NonNull SplashScreen installSplashScreen(@NonNull Activity receiver)
```

Creates a `https://developer.android.com/reference/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/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/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)`.

### setKeepOnScreenCondition

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

```
public final void setKeepOnScreenCondition(
    @NonNull SplashScreen.KeepOnScreenCondition condition
)
```

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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen.KeepOnScreenCondition condition` | 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)

```
public final void setOnExitAnimationListener(
    @NonNull SplashScreen.OnExitAnimationListener listener
)
```

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/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener listener` | The `https://developer.android.com/reference/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/androidx/core/splashscreen/SplashScreen#setKeepOnScreenCondition(androidx.core.splashscreen.SplashScreen.KeepOnScreenCondition)` |   |
| `https://developer.android.com/reference/androidx/core/splashscreen/SplashScreen.OnExitAnimationListener` |   |
| `https://developer.android.com/reference/androidx/core/splashscreen/SplashScreenViewProvider` |   |