Skip to content

feat(splash-screen): implement launchFadeOutDuration support on iOS #2524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
OS-ruimoreiramendes merged 2 commits into from
May 12, 2026
Merged

feat(splash-screen): implement launchFadeOutDuration support on iOS #2524

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b37e708
fix(splash-screen): change launchFadeOutDuration default to 0
OS-ruimoreiramendes May 8, 2026
0ea854f
Merge branch 'next' into fix/splash-screen-launch-fade-out-duration
OS-ruimoreiramendes May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion splash-screen/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ These config values are available:
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----- |
| **`launchShowDuration`** | <code>number</code> | How long to show the launch splash screen when autoHide is enabled (in ms) | <code>500</code> | 1.0.0 |
| **`launchAutoHide`** | <code>boolean</code> | Whether to auto hide the splash after launchShowDuration. | <code>true</code> | 1.0.0 |
| **`launchFadeOutDuration`** | <code>number</code> | Duration for the fade out animation of the launch splash screen (in ms) Only available for Android, when using the Android 12 Splash Screen API. | <code>200</code> | 4.2.0 |
| **`launchFadeOutDuration`** | <code>number</code> | Duration for the fade out animation of the launch splash screen (in ms) On Android, only available when using the Android 12 Splash Screen API. | <code>200</code> | 4.2.0 |
| **`backgroundColor`** | <code>string</code> | Color of the background of the Splash Screen in hex format, #RRGGBB or #RRGGBBAA. Doesn't work if `useDialog` is true or on launch when using the Android 12 API. | | 1.0.0 |
| **`androidSplashResourceName`** | <code>string</code> | Name of the resource to be used as Splash Screen. Doesn't work on launch when using the Android 12 API. Only available on Android. | <code>splash</code> | 1.0.0 |
| **`androidScaleType`** | <code>'CENTER' \| 'CENTER_CROP' \| 'CENTER_INSIDE' \| 'FIT_CENTER' \| 'FIT_END' \| 'FIT_START' \| 'FIT_XY' \| 'MATRIX'</code> | The [ImageView.ScaleType](https://developer.android.com/reference/android/widget/ImageView.ScaleType) used to scale the Splash Screen image. Doesn't work if `useDialog` is true or on launch when using the Android 12 API. Only available on Android. | <code>FIT_XY</code> | 1.0.0 |
Expand Down
7 changes: 6 additions & 1 deletion splash-screen/ios/Sources/SplashScreenPlugin/SplashScreen.swift
View file
Open in desktop
Comment thread
OS-pedrogustavobilro marked this conversation as resolved.
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,23 @@ import Capacitor
var config: SplashScreenConfig = SplashScreenConfig()
var hideTask: Any?
var isVisible: Bool = false
var isLaunchSplash: Bool = false

init(parentView: UIView, config: SplashScreenConfig) {
self.parentView = parentView
self.config = config
}

public func showOnLaunch() {
isLaunchSplash = true
buildViews()
if self.config.launchShowDuration == 0 {
return
}
var settings = SplashScreenSettings()
settings.showDuration = config.launchShowDuration
settings.fadeInDuration = config.launchFadeInDuration
settings.fadeOutDuration = config.launchFadeOutDuration
settings.autoHide = config.launchAutoHide
showSplash(settings: settings, completion: {}, isLaunchSplash: true)
}
Expand All @@ -32,7 +35,9 @@ import Capacitor
}

public func hide(settings: SplashScreenSettings) {
hideSplash(fadeOutDuration: settings.fadeOutDuration, isLaunchSplash: false)
let fadeOutDuration = self.isLaunchSplash ? config.launchFadeOutDuration : settings.fadeOutDuration
Copy link
Copy Markdown
Contributor

@OS-pedrogustavobilro OS-pedrogustavobilro May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you explain the rationale behind this logic? Didn't seem like the equivalent existed on Android but maybe I didn't see right.

Copy link
Copy Markdown
Contributor Author

@OS-ruimoreiramendes OS-ruimoreiramendes May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Android (using the Android 12 API), launchFadeOutDuration is applied inside OnExitAnimationListener, which is a system callback that runs before hide() is ever called from JS, so the system already knows it's closing the launch splash and applies the right duration at that point.
On iOS there's no equivalent system hook. The only way to dismiss the splash (including the launch one) is through hideSplash(), which is triggered by hide(). The problem is that hide() receives a SplashScreenSettings object coming from the js call, and that object has no context about whether it's hiding the launch splash or a programmatically shown one. Without the isLaunchSplash flag, hide() would always use settings.fadeOutDuration from the js parameters (default 200ms), ignoring the launchFadeOutDuration set in capacitor.config.ts.
So the flag is needed to let hide() decide:

"am I closing the launch splash, so use config.launchFadeOutDuration"
vs
"am I closing a programmatic splash, so use settings.fadeOutDuration from the js call".

Copy link
Copy Markdown
Contributor

@OS-pedrogustavobilro OS-pedrogustavobilro May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok makes sense, thanks for the detailed explanation!

self.isLaunchSplash = false
hideSplash(fadeOutDuration: fadeOutDuration, isLaunchSplash: false)
}

private func showSplash(settings: SplashScreenSettings, completion: @escaping () -> Void, isLaunchSplash: Bool) {
Expand Down
1 change: 1 addition & 0 deletions splash-screen/ios/Sources/SplashScreenPlugin/SplashScreenConfig.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,5 @@ public struct SplashScreenConfig {
var launchShowDuration = 500
var launchAutoHide = true
let launchFadeInDuration = 0
var launchFadeOutDuration = 0
}
1 change: 1 addition & 0 deletions splash-screen/ios/Sources/SplashScreenPlugin/SplashScreenPlugin.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ public class SplashScreenPlugin: CAPPlugin, CAPBridgedPlugin {

config.launchShowDuration = getConfig().getInt("launchShowDuration", config.launchShowDuration)
config.launchAutoHide = getConfig().getBoolean("launchAutoHide", config.launchAutoHide)
config.launchFadeOutDuration = getConfig().getInt("launchFadeOutDuration", config.launchFadeOutDuration)
return config
}

Expand Down
2 changes: 1 addition & 1 deletion splash-screen/src/definitions.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ declare module '@capacitor/cli' {
/**
* Duration for the fade out animation of the launch splash screen (in ms)
*
* Only available for Android, when using the Android 12 Splash Screen API.
* On Android, only available when using the Android 12 Splash Screen API.
*
* @since 4.2.0
* @default 200
Expand Down
Loading