From 68188c19578b6755cc7bf165cc298c194600f5cf Mon Sep 17 00:00:00 2001 From: Daniele Rolli Date: Fri, 27 Feb 2026 17:16:09 +0100 Subject: [PATCH 01/10] fix(ios): prevent black QuickType bar when using Magic Keyboard on iPad + Fix Keyboard on iOS 26 --- ios/Sources/KeyboardPlugin/Keyboard.m | 133 ++++++++++++++++++++++---- 1 file changed, 117 insertions(+), 16 deletions(-) diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index 29c0708..0c18622 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -18,6 +18,7 @@ Licensed to the Apache Software Foundation (ASF) under one #import "Keyboard.h" #import #import +#import #import #import #import @@ -48,12 +49,92 @@ @interface KeyboardPlugin () // protocol conformance for this class is implemented by a macro and clang isn't detecting that @implementation KeyboardPlugin +/// Heights below this on iPad are treated as QuickType bar, not a real keyboard +static const CGFloat QUICKTYPE_IGNORE_THRESHOLD = 100.0; + NSTimer *hideTimer; NSString* UIClassString; NSString* WKClassString; NSString* UITraitsClassString; double stageManagerOffset; +#pragma mark - Helpers + +- (UIWindow *)currentKeyWindow { + UIWindow *window = nil; + if ([[[UIApplication sharedApplication] delegate] respondsToSelector:@selector(window)]) { + window = [[[UIApplication sharedApplication] delegate] window]; + } + if (!window && @available(iOS 13.0, *)) { + NSPredicate *predicate = [NSPredicate predicateWithFormat:@"self isKindOfClass: %@", UIWindowScene.class]; + UIScene *scene = [UIApplication.sharedApplication.connectedScenes.allObjects filteredArrayUsingPredicate:predicate].firstObject; + window = [[(UIWindowScene*)scene windows] filteredArrayUsingPredicate:[NSPredicate predicateWithFormat:@"isKeyWindow == YES"]].firstObject; + } + return window; +} + +- (void)forceBackdropColor:(UIColor *)color { + UIWindow *w = [self currentKeyWindow]; + if (w) { + dispatch_async(dispatch_get_main_queue(), ^{ + w.backgroundColor = color; + }); + } +} + +- (BOOL)isIPad { + return ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad); +} + +- (BOOL)shouldIgnoreResizeForHeight:(double)height { + if (![self isIPad]) return NO; + if (height <= 0.0) return NO; + return (height < QUICKTYPE_IGNORE_THRESHOLD); +} + +#pragma mark - Lifecycle + +- (UIColor *)colorFromCssColorString:(NSString *)cssColor { + NSString *trimmed = [cssColor stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]]; + + if ([trimmed hasPrefix:@"rgb"]) { + NSString *clean = [[trimmed stringByReplacingOccurrencesOfString:@"rgb(" withString:@""] stringByReplacingOccurrencesOfString:@")" withString:@""]; + NSArray *parts = [clean componentsSeparatedByString:@","]; + if (parts.count >= 3) { + CGFloat r = [parts[0] floatValue] / 255.0; + CGFloat g = [parts[1] floatValue] / 255.0; + CGFloat b = [parts[2] floatValue] / 255.0; + return [UIColor colorWithRed:r green:g blue:b alpha:1.0]; + } + } + + if ([trimmed hasPrefix:@"#"]) { + unsigned rgbValue = 0; + NSScanner *scanner = [NSScanner scannerWithString:trimmed]; + [scanner setScanLocation:1]; + if ([scanner scanHexInt:&rgbValue]) { + CGFloat r = ((rgbValue & 0xFF0000) >> 16) / 255.0; + CGFloat g = ((rgbValue & 0x00FF00) >> 8) / 255.0; + CGFloat b = (rgbValue & 0x0000FF) / 255.0; + return [UIColor colorWithRed:r green:g blue:b alpha:1.0]; + } + } + + return [UIColor whiteColor]; // fallback +} + +- (void)updateBackdropColorFromDOM { + if (!self.webView) return; + [self.webView evaluateJavaScript:@"window.getComputedStyle(document.body).backgroundColor" completionHandler:^(id result, NSError *error) { + if (result && [result isKindOfClass:[NSString class]]) { + UIColor *color = [self colorFromCssColorString:(NSString *)result]; + if (color) { + [self forceBackdropColor:color]; + } + } + }]; +} + - (void)load { self.disableScroll = !self.bridge.config.scrollingEnabled; @@ -97,8 +178,17 @@ - (void)load [nc removeObserver:self.webView name:UIKeyboardWillShowNotification object:nil]; [nc removeObserver:self.webView name:UIKeyboardWillChangeFrameNotification object:nil]; [nc removeObserver:self.webView name:UIKeyboardDidChangeFrameNotification object:nil]; -} + // Make WKWebView transparent + if (self.webView) { + self.webView.opaque = NO; + self.webView.backgroundColor = UIColor.clearColor; + self.webView.scrollView.backgroundColor = UIColor.clearColor; + } + + // Force DOM color on load + [self updateBackdropColorFromDOM]; +} #pragma mark Keyboard events @@ -124,11 +214,15 @@ - (void)onKeyboardWillShow:(NSNotification *)notification if (hideTimer != nil) { [hideTimer invalidate]; } + + // Force DOM color whenever keyboard shows + [self updateBackdropColorFromDOM]; + CGRect rect = [[notification.userInfo valueForKey:UIKeyboardFrameEndUserInfoKey] CGRectValue]; double height = rect.size.height; - if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad) { + if ([self isIPad]) { if (stageManagerOffset > 0) { height = stageManagerOffset; } else { @@ -142,8 +236,14 @@ - (void)onKeyboardWillShow:(NSNotification *)notification } } + BOOL ignored = [self shouldIgnoreResizeForHeight:height]; + if (ignored) { + NSLog(@"KeyboardPlugin: Ignoring QuickType Bar (%.1f) -> treat as 0.", height); + height = 0.0; + } + double duration = [[notification.userInfo valueForKey:UIKeyboardAnimationDurationUserInfoKey] doubleValue]+0.2; - [self setKeyboardHeight:height delay:duration]; + [self setKeyboardHeight:(int)height delay:duration]; [self resetScrollView]; NSString * data = [NSString stringWithFormat:@"{ 'keyboardHeight': %d }", (int)height]; @@ -157,6 +257,18 @@ - (void)onKeyboardDidShow:(NSNotification *)notification CGRect rect = [[notification.userInfo valueForKey:UIKeyboardFrameEndUserInfoKey] CGRectValue]; double height = rect.size.height; + if ([self isIPad]) { + if (stageManagerOffset > 0) { + height = stageManagerOffset; + } + } + + BOOL ignored = [self shouldIgnoreResizeForHeight:height]; + if (ignored) { + NSLog(@"KeyboardPlugin: (didShow) Ignoring QuickType Bar (%.1f) -> report 0.", height); + height = 0.0; + } + [self resetScrollView]; NSString * data = [NSString stringWithFormat:@"{ 'keyboardHeight': %d }", (int)height]; @@ -205,19 +317,8 @@ - (void)resizeElement:(NSString *)element withPaddingBottom:(int)paddingBottom w - (void)_updateFrame { CGRect f, wf = CGRectZero; - UIWindow * window = nil; - - if ([[[UIApplication sharedApplication] delegate] respondsToSelector:@selector(window)]) { - window = [[[UIApplication sharedApplication] delegate] window]; - } - - if (!window) { - if (@available(iOS 13.0, *)) { - NSPredicate *predicate = [NSPredicate predicateWithFormat:@"self isKindOfClass: %@", UIWindowScene.class]; - UIScene *scene = [UIApplication.sharedApplication.connectedScenes.allObjects filteredArrayUsingPredicate:predicate].firstObject; - window = [[(UIWindowScene*)scene windows] filteredArrayUsingPredicate:[NSPredicate predicateWithFormat:@"isKeyWindow == YES"]].firstObject; - } - } + UIWindow *window = [self currentKeyWindow]; + if (window) { f = [window bounds]; } From e9bad398468a82adda9a2ff5dd7b6b110bd4acc1 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Thu, 14 May 2026 13:07:33 -0500 Subject: [PATCH 02/10] fix(ios): use configured background color for keyboard backdrop --- ios/Sources/KeyboardPlugin/Keyboard.m | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index 0c18622..3dcf235 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -123,6 +123,14 @@ - (UIColor *)colorFromCssColorString:(NSString *)cssColor { return [UIColor whiteColor]; // fallback } +- (void)updateBackdropColor { + if (self.bridge.config.backgroundColor) { + [self forceBackdropColor:self.bridge.config.backgroundColor]; + } else { + [self updateBackdropColorFromDOM]; + } +} + - (void)updateBackdropColorFromDOM { if (!self.webView) return; [self.webView evaluateJavaScript:@"window.getComputedStyle(document.body).backgroundColor" completionHandler:^(id result, NSError *error) { @@ -179,15 +187,14 @@ - (void)load [nc removeObserver:self.webView name:UIKeyboardWillChangeFrameNotification object:nil]; [nc removeObserver:self.webView name:UIKeyboardDidChangeFrameNotification object:nil]; - // Make WKWebView transparent - if (self.webView) { - self.webView.opaque = NO; - self.webView.backgroundColor = UIColor.clearColor; - self.webView.scrollView.backgroundColor = UIColor.clearColor; - } - - // Force DOM color on load - [self updateBackdropColorFromDOM]; +// // Make WKWebView transparent +// if (self.webView) { +// self.webView.opaque = NO; +// self.webView.backgroundColor = UIColor.clearColor; +// self.webView.scrollView.backgroundColor = UIColor.clearColor; +// } + + [self updateBackdropColor]; } #pragma mark Keyboard events @@ -216,7 +223,7 @@ - (void)onKeyboardWillShow:(NSNotification *)notification } // Force DOM color whenever keyboard shows - [self updateBackdropColorFromDOM]; + [self updateBackdropColor]; CGRect rect = [[notification.userInfo valueForKey:UIKeyboardFrameEndUserInfoKey] CGRectValue]; From 0ebaaab3d650e65b409bcc7b513353c35d3bbf52 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Mon, 18 May 2026 09:58:09 -0500 Subject: [PATCH 03/10] Uncommenting transparent WKWebView --- ios/Sources/KeyboardPlugin/Keyboard.m | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index 3dcf235..b741af8 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -187,12 +187,12 @@ - (void)load [nc removeObserver:self.webView name:UIKeyboardWillChangeFrameNotification object:nil]; [nc removeObserver:self.webView name:UIKeyboardDidChangeFrameNotification object:nil]; -// // Make WKWebView transparent -// if (self.webView) { -// self.webView.opaque = NO; -// self.webView.backgroundColor = UIColor.clearColor; -// self.webView.scrollView.backgroundColor = UIColor.clearColor; -// } + // Make WKWebView transparent + if (self.webView) { + self.webView.opaque = NO; + self.webView.backgroundColor = UIColor.clearColor; + self.webView.scrollView.backgroundColor = UIColor.clearColor; + } [self updateBackdropColor]; } From 08e5f52caebee71ea2883c26c12ba4aa766858d9 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Mon, 18 May 2026 10:08:48 -0500 Subject: [PATCH 04/10] fix(ios): support transparent and rgba colors in CSS color parser --- ios/Sources/KeyboardPlugin/Keyboard.m | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index b741af8..a447bd5 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -97,14 +97,21 @@ - (BOOL)shouldIgnoreResizeForHeight:(double)height { - (UIColor *)colorFromCssColorString:(NSString *)cssColor { NSString *trimmed = [cssColor stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]]; + if ([trimmed isEqualToString:@"transparent"]) { + return [UIColor clearColor]; + } + if ([trimmed hasPrefix:@"rgb"]) { - NSString *clean = [[trimmed stringByReplacingOccurrencesOfString:@"rgb(" withString:@""] stringByReplacingOccurrencesOfString:@")" withString:@""]; + NSRange parenRange = [trimmed rangeOfString:@"("]; + NSString *clean = parenRange.location != NSNotFound ? [trimmed substringFromIndex:parenRange.location + 1] : trimmed; + clean = [clean stringByReplacingOccurrencesOfString:@")" withString:@""]; NSArray *parts = [clean componentsSeparatedByString:@","]; if (parts.count >= 3) { CGFloat r = [parts[0] floatValue] / 255.0; CGFloat g = [parts[1] floatValue] / 255.0; CGFloat b = [parts[2] floatValue] / 255.0; - return [UIColor colorWithRed:r green:g blue:b alpha:1.0]; + CGFloat a = parts.count >= 4 ? [parts[3] floatValue] : 1.0; + return [UIColor colorWithRed:r green:g blue:b alpha:a]; } } From 6dd92665460021560de7c25c868e20ee044046f3 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Mon, 18 May 2026 10:24:17 -0500 Subject: [PATCH 05/10] fix(ios): use screen-relative threshold and webview-aware height on iPad --- ios/Sources/KeyboardPlugin/Keyboard.m | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index a447bd5..1accbe1 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -49,9 +49,6 @@ @interface KeyboardPlugin () // protocol conformance for this class is implemented by a macro and clang isn't detecting that @implementation KeyboardPlugin -/// Heights below this on iPad are treated as QuickType bar, not a real keyboard -static const CGFloat QUICKTYPE_IGNORE_THRESHOLD = 100.0; - NSTimer *hideTimer; NSString* UIClassString; NSString* WKClassString; @@ -89,7 +86,8 @@ - (BOOL)isIPad { - (BOOL)shouldIgnoreResizeForHeight:(double)height { if (![self isIPad]) return NO; if (height <= 0.0) return NO; - return (height < QUICKTYPE_IGNORE_THRESHOLD); + CGFloat screenHeight = UIScreen.mainScreen.bounds.size.height; + return (height / screenHeight) < 0.20; } #pragma mark - Lifecycle @@ -274,6 +272,12 @@ - (void)onKeyboardDidShow:(NSNotification *)notification if ([self isIPad]) { if (stageManagerOffset > 0) { height = stageManagerOffset; + } else { + CGRect webViewAbsolute = [self.webView convertRect:self.webView.frame toCoordinateSpace:self.webView.window.screen.coordinateSpace]; + height = (webViewAbsolute.size.height + webViewAbsolute.origin.y) - (UIScreen.mainScreen.bounds.size.height - rect.size.height); + if (height < 0) { + height = 0; + } } } From f06eac66a37b7e8100c80c4b0e0dce02118bd036 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Tue, 19 May 2026 09:27:38 -0500 Subject: [PATCH 06/10] fmt --- .../capacitorjs/plugins/keyboard/KeyboardPlugin.java | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/android/src/main/java/com/capacitorjs/plugins/keyboard/KeyboardPlugin.java b/android/src/main/java/com/capacitorjs/plugins/keyboard/KeyboardPlugin.java index bf6735a..40fe0b7 100644 --- a/android/src/main/java/com/capacitorjs/plugins/keyboard/KeyboardPlugin.java +++ b/android/src/main/java/com/capacitorjs/plugins/keyboard/KeyboardPlugin.java @@ -26,13 +26,10 @@ public void load() { @PluginMethod public void show(final PluginCall call) { execute(() -> - new Handler(Looper.getMainLooper()).postDelayed( - () -> { - implementation.show(); - call.resolve(); - }, - 350 - ) + new Handler(Looper.getMainLooper()).postDelayed(() -> { + implementation.show(); + call.resolve(); + }, 350) ); } From 6224ccb341f516d00b66ef9c33e41fcd1a5ce8a3 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Mon, 1 Jun 2026 11:22:19 -0500 Subject: [PATCH 07/10] removing unneeded @available(iOS 13.0, *) --- ios/Sources/KeyboardPlugin/Keyboard.m | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index 1accbe1..d994192 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -62,7 +62,7 @@ - (UIWindow *)currentKeyWindow { if ([[[UIApplication sharedApplication] delegate] respondsToSelector:@selector(window)]) { window = [[[UIApplication sharedApplication] delegate] window]; } - if (!window && @available(iOS 13.0, *)) { + if (!window) { NSPredicate *predicate = [NSPredicate predicateWithFormat:@"self isKindOfClass: %@", UIWindowScene.class]; UIScene *scene = [UIApplication.sharedApplication.connectedScenes.allObjects filteredArrayUsingPredicate:predicate].firstObject; window = [[(UIWindowScene*)scene windows] filteredArrayUsingPredicate:[NSPredicate predicateWithFormat:@"isKeyWindow == YES"]].firstObject; From 0eea350d6d17d3b506e35bf417288f13dddb67e4 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Mon, 1 Jun 2026 12:13:11 -0500 Subject: [PATCH 08/10] removing transparent webview --- ios/Sources/KeyboardPlugin/Keyboard.m | 7 ------- 1 file changed, 7 deletions(-) diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index d994192..cc7b089 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -192,13 +192,6 @@ - (void)load [nc removeObserver:self.webView name:UIKeyboardWillChangeFrameNotification object:nil]; [nc removeObserver:self.webView name:UIKeyboardDidChangeFrameNotification object:nil]; - // Make WKWebView transparent - if (self.webView) { - self.webView.opaque = NO; - self.webView.backgroundColor = UIColor.clearColor; - self.webView.scrollView.backgroundColor = UIColor.clearColor; - } - [self updateBackdropColor]; } From 7366fca7de6792993e7262618d7fd97192607185 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Tue, 2 Jun 2026 12:14:49 -0500 Subject: [PATCH 09/10] feat(ios): add autoBackdropColor config to gate DOM-derived backdrop --- ios/Sources/KeyboardPlugin/Keyboard.m | 2 +- src/definitions.ts | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index cc7b089..53026ab 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -131,7 +131,7 @@ - (UIColor *)colorFromCssColorString:(NSString *)cssColor { - (void)updateBackdropColor { if (self.bridge.config.backgroundColor) { [self forceBackdropColor:self.bridge.config.backgroundColor]; - } else { + } else if ([[self getConfig] getBoolean:@"autoBackdropColor": NO]) { [self updateBackdropColorFromDOM]; } } diff --git a/src/definitions.ts b/src/definitions.ts index c0c98b9..b6b8a4f 100644 --- a/src/definitions.ts +++ b/src/definitions.ts @@ -41,6 +41,24 @@ declare module '@capacitor/cli' { * @example true */ resizeOnFullScreen?: boolean; + + /** + * Auto-derive the keyboard backdrop color from the WebView's DOM. + * + * When enabled, every time the keyboard is about to show the plugin reads + * the web app page DOM background color and tints the + * key window (the area visible behind the keyboard) with that color. This + * keeps the backdrop in sync with the page's body background and avoids + * visible artifacts. Has no effect if the root Capacitor `backgroundColor` config is set; + * that explicit color always takes precedence. + * + * Only available on iOS. + * + * @since 8.1.0 + * @default false + * @example true + */ + autoBackdropColor?: boolean; }; } } From 6bfa18d3996e074f5c0c27a0cca3e7dc17a627c9 Mon Sep 17 00:00:00 2001 From: Joseph Pender Date: Wed, 3 Jun 2026 08:58:54 -0500 Subject: [PATCH 10/10] feat(ios): make autoBackdropColor a tri-state mode (off/auto/dom) --- example-app/capacitor.config.ts | 8 +++++++- ios/Sources/KeyboardPlugin/Keyboard.m | 12 +++++++++--- src/definitions.ts | 21 +++++++++++---------- 3 files changed, 27 insertions(+), 14 deletions(-) diff --git a/example-app/capacitor.config.ts b/example-app/capacitor.config.ts index f7981af..a139aed 100644 --- a/example-app/capacitor.config.ts +++ b/example-app/capacitor.config.ts @@ -3,7 +3,13 @@ import type { CapacitorConfig } from '@capacitor/cli'; const config: CapacitorConfig = { appId: 'io.ionic.starter', appName: 'CAP-KEYB-SAMPLE', - webDir: 'dist' + webDir: 'dist', + backgroundColor: "#fffb38", + plugins: { + Keyboard: { + autoBackdropColor: 'auto' + } + } }; export default config; diff --git a/ios/Sources/KeyboardPlugin/Keyboard.m b/ios/Sources/KeyboardPlugin/Keyboard.m index 53026ab..54a6694 100644 --- a/ios/Sources/KeyboardPlugin/Keyboard.m +++ b/ios/Sources/KeyboardPlugin/Keyboard.m @@ -129,9 +129,15 @@ - (UIColor *)colorFromCssColorString:(NSString *)cssColor { } - (void)updateBackdropColor { - if (self.bridge.config.backgroundColor) { - [self forceBackdropColor:self.bridge.config.backgroundColor]; - } else if ([[self getConfig] getBoolean:@"autoBackdropColor": NO]) { + NSString *mode = [[self getConfig] getString:@"autoBackdropColor": @"off"]; + + if ([mode isEqualToString:@"auto"]) { + if (self.bridge.config.backgroundColor) { + [self forceBackdropColor:self.bridge.config.backgroundColor]; + } else { + [self updateBackdropColorFromDOM]; + } + } else if ([mode isEqualToString:@"dom"]) { [self updateBackdropColorFromDOM]; } } diff --git a/src/definitions.ts b/src/definitions.ts index b6b8a4f..30968dd 100644 --- a/src/definitions.ts +++ b/src/definitions.ts @@ -43,22 +43,23 @@ declare module '@capacitor/cli' { resizeOnFullScreen?: boolean; /** - * Auto-derive the keyboard backdrop color from the WebView's DOM. + * Controls how the keyboard backdrop color (the area visible behind the + * keyboard) is set every time the keyboard is about to show. * - * When enabled, every time the keyboard is about to show the plugin reads - * the web app page DOM background color and tints the - * key window (the area visible behind the keyboard) with that color. This - * keeps the backdrop in sync with the page's body background and avoids - * visible artifacts. Has no effect if the root Capacitor `backgroundColor` config is set; - * that explicit color always takes precedence. + * - `'off'` — Do not tint the backdrop. + * - `'auto'` — Use the `backgroundColor` set in the Capacitor config; + * otherwise derive the color from the web app's DOM body background. + * - `'dom'` — Always derive the color from the web app's DOM body + * background, ignoring the `backgroundColor` config. If the DOM + * has no resolvable background, the backdrop is left untouched. * * Only available on iOS. * * @since 8.1.0 - * @default false - * @example true + * @default "off" + * @example "auto" */ - autoBackdropColor?: boolean; + autoBackdropColor?: 'off' | 'auto' | 'dom'; }; } }