
capacitor-ui
Mobile UI skills for Ionic, Konsta UI, Tailwind, safe-area handling, and iPad/foldable resizability in Capacitor apps.
- version
- 1.1.0
- GitHub stars
- 79
Install
/plugin install capacitor-ui@capgo-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add Cap-go/capgo-skills.
Contents
Discovered from sourceSkills 5
Resizable Windows for Capacitor iOS Apps
A Capacitor app is a full-window WKWebView in CAPBridgeViewController. The web view follows its window. The work is to make the web layout respond to width changes, and to remove native code (app, custom code, plugins) that assumes one full-screen window.
When to Use
TRIGGER when:
- Preparing an app for iPad multitasking, Stage Manager, windowed iPad apps, the foldable iPhone, or external displays
- The layout breaks or does not update when the window is resized
- A native overlay from a plugin (scanner, camera preview, custom sheet) is the wrong size or position in split view
- Xcode or App Store Connect warns about
UIRequiresFullScreen, missing iPad orientations, or launch screen requirements - The user asks to remove
UIScreen.main,userInterfaceIdiom,interfaceOrientationor AppDelegate lifecycle use
Do not use:
- CSS
env(safe-area-inset-*)setup and notch padding only:safe-area-handling - Moving AppDelegate to SceneDelegate:
capacitor-uiscene-migration(prerequisite for Xcode 27) - Keyboard overlap:
capacitor-keyboard - Tailwind breakpoints only:
tailwind-capacitor
Facts that drive the plan
- iOS 27 ignores
UIRequiresFullScreenand resizes the scene anyway (TN3192). Never delete the key silently: deleting it makes the app resizable at once on current iOS. Never addUIRequiresFullScreenIgnoredStartingWithVersionon your own: its value decides which releases keep the old behavior. Both are the user's call, after testing. - The iOS 27 SDK requires a launch screen declaration. Without one the upload is rejected with
ITMS-90870. Capacitor templates setUILaunchStoryboardName; keep it. - Xcode 27 requires the scene lifecycle. Capacitor 8.5 templates ship
SceneDelegate.swift. Without it, AppDelegate lifecycle methods are the only signal, which is wrong in multi-window. Runcapacitor-uiscene-migrationfirst ifUIApplicationSceneManifestis missing. - Keep
UIApplicationSupportsMultipleScenes = false. Each scene would create its ownCAPBridgeViewController, with a second WebView and plugin set. Capacitor added scene-scoped notifications in 8.5 so plugins can prepare, but multi-window is not supported in the templates. Resizing works with a single scene. CAPBridgeViewControllerbuildssupportedInterfaceOrientationsfrom the iPhone keyUISupportedInterfaceOrientationsonly, not fromUISupportedInterfaceOrientations~ipad(Capacitor 8.5 source). An iPad that declares all four orientations can still be locked by the bridge mask. Report it; overridesupportedInterfaceOrientationsin a bridge subclass only if the user wants different iPad behavior.- The web layer gets resize events for free.
WKWebViewresizes with the window and firesresize. Breakage comes from layout code that reads the device instead of the viewport. - Plugins are third-party code. Edits to
node_modulesare lost on install. Report plugin findings, upgrade the plugin, open an issue upstream, or usepatch-packageonly as a stopgap, with user approval.
References
Only load a reference when its topic is in play.
| File | Load when |
|---|---|
| references/info-plist-and-scenes.md | Checking Info.plist keys, orientation masks, scene lifecycle and the AppDelegate methods that stop firing |
| references/web-layer.md | Auditing and fixing CSS/JS layout: viewport, units, device sniffing, safe areas that change at runtime |
| references/native-replacements.md | Replacing UIScreen.main, orientation, idiom, key window, lifecycle and hard-coded insets in Swift/ObjC |
| references/plugin-audit.md | Scanning plugins in node_modules, triage, and what plugin authors should change |
| references/swiftui-in-plugins.md | A plugin or app presents native SwiftUI screens that must resize; iOS 27 SDK SwiftUI changes |
Script: scripts/scan-legacy-apis.sh scans ios/App/App and every node_modules/**/ios folder and prints the resize-related Info.plist keys. Read-only.
Workflow
1. Prerequisites (read-only)
Read ios/App/App/Info.plist, AppDelegate.swift, SceneDelegate.swift, the @capacitor/ios version, and the TARGETED_DEVICE_FAMILY build setting (1,2 = iPhone and iPad). Report:
| Check | OK when | Otherwise |
|---|---|---|
| Launch screen | UILaunchStoryboardName or UILaunchScreen present | Report ITMS-90870 risk |
| Scene lifecycle | UIApplicationSceneManifest present, SceneDelegate.swift in the target | Send to capacitor-uiscene-migration first |
| iPad orientations | UISupportedInterfaceOrientations~ipad lists all four, or no iPad key | Name the missing ones. Mention the bridge mask fact above |
| Full-screen opt-out | UIRequiresFullScreen absent | Report that iOS 27 ignores it. Ask the user before changing it |
2. Scan
bash <skill>/scripts/scan-legacy-apis.sh .
Also scan the web code (references/web-layer.md):
grep -rnE 'screen\.(width|height|availWidth)|window\.orientation|orientationchange|\b100vh\b|navigator\.userAgent.*(iPad|iPhone)|isPlatform\(.(ipad|tablet|iphone)|innerWidth' src --include='*.{ts,tsx,js,jsx,vue,svelte,css,scss}'
Make a TODO list with one entry per file. Large projects: process files in batches of 3 to 5. Every file in the list gets a change or a written reason for no change.
3. Report, then ask
Group the findings into: app web code, app native code, plugins (by package), Info.plist. For each, state the fix. Ask the user before:
- changing
UIRequiresFullScreen, orientation keys or the orientation mask, - changing a public method signature in shared native code,
- patching a plugin in
node_modules.
4. Fix
- Web layer first. It is usually the whole fix: references/web-layer.md.
- App native code: references/native-replacements.md. Only edit lines that contain the target API. Keep every
if/elsebranch and#availableguard. Never replace a dynamic value with a literal, and never replace one global (UIScreen.main) with another (UIApplication.shared,UITraitCollection.current,UIDevice.current). - Empty template stubs (
applicationDidBecomeActiveand friends with only comments) are harmless. Move them only if they contain code. - Plugins: references/plugin-audit.md.
5. Verify
npx cap sync ios
xcrun simctl list devices available | grep -i ipad
npx cap run ios --target <iPad-simulator-UDID>
- On the iPad simulator (iPadOS 26+), switch the app to a window and drag its corner. Check narrow, medium and wide sizes. Also try Split View with another app.
- Rotate during each size. Open and close the keyboard in a narrow window.
- Check native overlays from plugins (scanner, camera preview, pickers) at a narrow width.
- Background and foreground the app. JS
pause/resumemust fire. - If Xcode offers a foldable iPhone simulator, test fold and unfold the same way.
- Re-run the scan. Remaining hits must each have a written reason (non-layout use such as camera capture orientation or analytics).
Error Handling
| Symptom | Cause | Fix |
|---|---|---|
| Layout stuck at the old size after resize | JS cached window.innerWidth / screen.width at startup, or CSS uses 100vh | Read sizes on resize or use CSS; replace 100vh with 100dvh |
| Content under the status bar or home indicator only in some window sizes | Safe-area insets were read once, or a side inset was mirrored to both sides | Use env(safe-area-inset-*) per edge in CSS; never cache them in JS |
| Plugin overlay covers the wrong area in split view | Plugin sizes its view from UIScreen.main.bounds | Update the plugin, or report upstream with the scan line |
| App launches but is not resizable on iOS 26 | UIRequiresFullScreen = true | Expected until the user removes it after testing |
Upload rejected with ITMS-90870 | No launch screen key | Restore UILaunchStoryboardName with LaunchScreen.storyboard |
pause / resume stop firing after adding SceneDelegate | Custom code in AppDelegate lifecycle methods | Move it to scene methods or observe notifications (references/info-plist-and-scenes.md) |
Related Skills
safe-area-handling: CSS env() variables and the status bar overlaycapacitor-uiscene-migration: SceneDelegate adoption, the prerequisite for scene-aware fixestailwind-capacitor: responsive breakpoints in Tailwindcapacitor-testing: simulator and device verification loopcapacitor-plugin-upgrade-v8-to-v9: when a plugin fix needs a new major version
Ionic Framework Design
When to Use
TRIGGER when:
- Writing or reviewing
Ion*/ion-*components in a Capacitor app - Theming:
--ion-color-*, dark mode, high contrast, per-platform styles - iOS vs Material Design mode looks wrong, or
modeoverrides misbehave - Upgrading Ionic 7/8 -> 9, or errors after
npm i @ionic/*@latest - Choosing Ionic vs another UI kit for a new Capacitor app
Do not use:
- Konsta UI components:
konsta-ui - Tailwind v4 install / config:
tailwind-capacitor - Notch / system bar padding outside Ionic:
safe-area-handling - Keyboard covering inputs:
capacitor-keyboard(Ionic apps useresize: 'ionic') - Leaving Appflow / Ionic Enterprise plugins:
ionic-appflow-migration,ionic-enterprise-sdk-migration
Versions (October 2026)
| Package | Current | Notes |
|---|---|---|
@ionic/core, @ionic/react, @ionic/vue, @ionic/angular | 9.x (latest) | 8.x on v8-lts tag |
ionicons | 8.x | |
| Ionic 9 minimums | Capacitor 7+, iOS 16+, Android Chromium 89+, Angular 18-22, React 18/19 + React Router 6.4+, Vue 3.5 + vue-router 5, TypeScript 5.4+ |
Check installed versions first: npm ls @ionic/core @ionic/react @ionic/vue @ionic/angular. Write code for the installed major; do not mix v8 and v9 APIs.
Workflow
Use the selected project and its installed dependencies. Package installation and migration tools execute code; limit them to the requested setup or upgrade, preserve the lockfile and existing changes, and review generated edits before running changed build scripts.
- Inspect framework, Ionic major, router version, global CSS imports,
setupIonicReact/IonicVue/provideIonicAngularconfig,capacitor.configKeyboard.resize. - Upgrading? Load references/ionic-9-migration.md; run
npx @ionic/migratein preview first, report findings, then apply. - Components: references/components.md for page shell, lists, forms, overlays, tabs.
- Theming: references/theming.md for colors, dark/high-contrast palettes, mode-specific CSS, shadow parts.
- Verify in both modes and on devices (below).
Only load a reference when its topic is in play.
Rules that prevent most Ionic bugs
- Every routed page =
IonPage>IonHeader+IonContent(+ optionalIonFooter). MissingIonPagebreaks transitions and lifecycle hooks. - Scroll lives in
ion-content. Do not makebodyor a wrapperdivscroll; useIonContentscrollToTop()/getScrollElement(). - Use
ion-router-outlet(IonRouterOutlet,IonTabs) for URL routing. In Ionic 9ion-navno longer integrates withion-router; keep it for local URL-less stacks inside a page. - Safe areas are handled through
--ion-safe-area-top|right|bottom|left(defaultenv()); do not add body padding on top. Requiresviewport-fit=cover. - Forms: put
label+labelPlacementon the control itself (<IonInput label="Email" labelPlacement="floating" />). Legacy<IonItem><IonLabel/><IonInput/></IonItem>labeling was removed in Ionic 8. - Overlays: prefer inline
<IonModal isOpen>/triggeror hooks (useIonModal,modalController) consistently; always handledidDismissto reset state. - Platform: style via
.ios/.mdclasses onhtmlormodeCSS selectors; useisPlatform('ios')only for behavior, nevernavigator.userAgent. - Icons: import only used icons (
import { heart } from 'ionicons/icons') and passicon={heart}; string names needaddIconsregistration in standalone/bundled builds.
Verification
- Build and sync:
npm run build && npx cap sync. - Run both modes in the browser: append
?ionic:mode=iosand?ionic:mode=mdto the dev URL; check headers, toolbars, lists, buttons. - Toggle OS dark mode (or add
ion-palette-darkto<html>if using the class palette); check contrast of custom colors. - Device check: iPhone with Dynamic Island + Android 15/16 gesture nav for header/tab bar insets; open keyboard on a form page.
- After upgrade:
grep -rn "ion-picker-legacy\|pickerController\|useIonPicker\|@ionic/angular/standalone\|autocorrect=\"off\"" src/returns nothing;npx tsc --noEmitpasses.
Error Handling
| Error / symptom | Cause | Fix |
|---|---|---|
Package path ./dist/... is not exported from package (webpack) / ERR_PACKAGE_PATH_NOT_EXPORTED (Node) for @ionic/core | Ionic 9 exports map; deep import | Import from @ionic/core, @ionic/core/components, @ionic/core/components/ion-*.js, @ionic/core/loader, @ionic/core/css/*.css |
Import errors or migrate warnings for @ionic/angular/standalone (Ionic 9) | Standalone imports moved | Import from @ionic/angular; lazy APIs from @ionic/angular/lazy |
React: Property 'component' does not exist on Route / IonRoute | Ionic 9 requires React Router 6 | element={<Page />}, Navigate instead of Redirect, useNavigate instead of useHistory |
| Autocorrect turned ON after upgrade | autocorrect="off" string is truthy in Ionic 9 | Remove the attribute or bind false |
ionChange no longer fires on re-selecting same option | Ionic 9 fires only on value change | Use ionDismiss for dismissal |
| Sheet modal handle now focusable / cycles breakpoints | Ionic 9 handleBehavior default cycle | handle-behavior="none" to restore |
| Styles missing, components unstyled | Core CSS not imported | Import @ionic/<fw>/css/core.css (+ structure/typography) once at entry |
| Dark mode never activates | No palette imported | Import css/palettes/dark.system.css (or .class.css + ion-palette-dark class) |
| Angular 21 view not updating after async work | Zoneless default in Ionic 9 + Angular 21 | Use signals / markForCheck(), or add provideZoneChangeDetection() |
Resources
- Ionic docs: https://ionicframework.com/docs
- Ionic 9 breaking changes: https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md
- Theming: https://ionicframework.com/docs/theming/basics
- Dark mode: https://ionicframework.com/docs/theming/dark-mode
Konsta UI for Capacitor
When to Use
TRIGGER when:
- Adding Konsta UI to a Capacitor app or choosing it over Ionic
- Upgrading Konsta v3/v4 (Tailwind v3
konstaConfig) to v5 (Tailwind v4) - Components unstyled, colors ignored,
ios:/material:classes do nothing - Navbar / Tabbar under the status bar or gesture bar
- Theme should follow platform (
ioson iPhone,materialon Android)
Do not use:
- Ionic Framework components or theming:
ionic-design - Tailwind install/config without Konsta:
tailwind-capacitor - Android SystemBars / edge-to-edge native config:
safe-area-handling - Keyboard overlap in forms:
capacitor-keyboard
Versions (October 2026)
| Konsta | Tailwind | Frameworks | Config style |
|---|---|---|---|
5.x (latest, 5.5.0) | v4 | React 19 (ref as prop), Vue 3, Svelte 5 (runes, snippets) | CSS: @import 'konsta/<fw>/theme.css' + @theme |
| 4.x | v3 | adds Svelte 5 types | JS: konstaConfig() in tailwind.config.js |
| 3.x and below | v3 | JS konstaConfig() |
Check first: npm ls konsta tailwindcss react vue svelte. Never mix v5 CSS setup with a tailwind.config.js konstaConfig wrapper.
Workflow
- Inspect versions, main CSS file,
tailwind.config.*,postcss.config.*,vite.config.*,index.htmlviewport meta, whether Ionic is also present. - Install / upgrade (below). For an existing Tailwind v3 project, migrate Tailwind first (
tailwind-capacitor). - Wrap the app in
App(orKonstaProviderwith Ionic/Framework7). - Build screens with components: references/components.md.
- Verify (below).
Only load a reference when its topic is in play.
Setup (v5, React shown; Vue/Svelte use konsta/vue/theme.css / konsta/svelte/theme.css)
npm i konsta tailwindcss @tailwindcss/vite
// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [react(), tailwindcss()] });
/* src/index.css */
@import 'tailwindcss';
@import 'konsta/react/theme.css';
@theme {
--color-brand-primary: #007aff; /* only --color-brand-* drive component colors */
--color-brand-red: #ff3b30; /* use with class k-color-brand-red */
}
import { Capacitor } from '@capacitor/core';
import { App } from 'konsta/react';
const theme = Capacitor.getPlatform() === 'android' ? 'material' : 'ios';
export default function Root() {
return (
<App theme={theme} safeAreas>
{/* pages */}
</App>
);
}
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
App props: theme ('ios' | 'material' | 'parent', default material), safeAreas (default true), dark, iosHoverHighlight, materialTouchRipple (global switches added in v5). Only one App per app.
Material Roboto font: add it yourself (Google Fonts link or self-hosted for offline). iOS uses the system font.
Migrating v4 -> v5
| v4 | v5 |
|---|---|
tailwind.config.js: module.exports = konstaConfig({...}) | Delete wrapper; @import 'konsta/react/theme.css' in CSS |
konstaConfig.colors.primary | @theme { --color-brand-primary: ... } |
| Per-component ripple config | Prefer the global App materialTouchRipple; check component types in your installed version |
SegmentedButton strong rounded | Removed; use Segmented theme-specific style props |
Link navbar/toolbar/tabbar props | Removed; context-driven |
React forwardRef usage / innerRef patterns | ref prop (React 19) |
| Svelte slots | {#snippet ...} |
Then run the Tailwind v4 upgrade (npx @tailwindcss/upgrade) if Tailwind itself is still v3; see tailwind-capacitor.
Traps
- With Ionic in the same app, use
KonstaProvider(notApp) and pick one owner for safe areas (Ionic's--ion-safe-area-*or Konsta'ssafe-areas), not both. - Dark mode in Konsta v5 is class-based (
@custom-variant dark (&:where(.dark, .dark *))in its CSS): toggledarkon<html>, setApp dark, and match native bars withSystemBars.setStyle. - Konsta's own docs show
user-scalable=no, maximum-scale=1; prefer allowing zoom for accessibility and fix iOS input zoom with 16px inputs instead. - Modals/side panels that are not full-screen need
no-safe-areas(orno-safe-areas-topetc.) to avoid extra padding. - Konsta is UI only: no router, no page transitions. Pair with React Router / Vue Router / SvelteKit and handle Android back button with
@capacitor/appbackButton.
Verification
npm run build && npx cap sync, run on iOS and Android.- Inspect
<html>/root:.k-iosor.k-materialclass present;ios:/material:utilities apply. - Navbar clears the Dynamic Island; Tabbar clears the home indicator and Android gesture bar (Android 15+ edge-to-edge).
- Toggle dark mode; components and status bar icons switch together.
- Leftover check:
grep -rn "konstaConfig\|konsta/config" .returns nothing on v5.
Error Handling
| Error / symptom | Cause | Fix |
|---|---|---|
Cannot find module 'konsta/config' | v5 removed JS config | Use CSS @import 'konsta/react/theme.css' |
| Components render unstyled | Theme CSS not imported, or Tailwind not scanning (no @tailwindcss/vite / @tailwindcss/postcss) | Import theme after @import 'tailwindcss'; add the Tailwind plugin |
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin | Tailwind v4 PostCSS plugin moved | Use @tailwindcss/postcss or @tailwindcss/vite |
| Brand color ignored | Variable not named --color-brand-*, or defined outside @theme | Rename inside @theme |
ios: classes have no effect | App/KonstaProvider missing, so no .k-ios ancestor | Wrap app |
React warning about ref / forwardRef after upgrade | React 18 with Konsta 5 | Upgrade to React 19 or stay on Konsta 4 |
| Double top padding | Konsta safeAreas + Ionic or custom env() padding | Keep one owner |
Resources
- Konsta UI: https://konstaui.com
- React installation: https://konstaui.com/react/installation
- Safe areas: https://konstaui.com/react/safe-areas
- Colors: https://konstaui.com/react/colors
- Changelog: https://github.com/konstaui/konsta/blob/master/CHANGELOG.md
Safe Area Handling in Capacitor
When to Use
TRIGGER when:
- Content renders under the status bar, notch, Dynamic Island, cutout, home indicator, or Android navigation/gesture bar
env(safe-area-inset-*)is0pxon Android, or correct only after rotation- Layout broke after Capacitor 8 upgrade or raising
targetSdkVersionto 35/36 StatusBar.setOverlaysWebView/setBackgroundColorstopped working on Android- Landscape / split-screen / iPad windowed layouts have wrong side padding
Do not use:
- Keyboard covering inputs:
capacitor-keyboard - Ionic
ion-header/ion-toolbartheming:ionic-design; KonstasafeAreas:konsta-ui - Tailwind plugin/utility setup:
tailwind-capacitor - iOS scene sizing,
UIScreen.main, multi-window:capacitor-ios-resizability - Splash screen colors:
capacitor-splash-screen
Facts that drive every decision
| Platform / version | Behavior |
|---|---|
| iOS (all) | WebView is full-screen. env(safe-area-inset-*) works only with viewport-fit=cover. ios.contentInset defaults to never. |
| Android, Capacitor <= 7 | android.adjustMarginsForEdgeToEdge config could add native margins. |
| Android, Capacitor 8+ | adjustMarginsForEdgeToEdge removed. SystemBars core plugin (in @capacitor/core) handles insets. |
| Android 15 (targetSdk 35) | Edge-to-edge enforced; opt-out via windowOptOutEdgeToEdgeEnforcement still possible. |
| Android 16 (targetSdk 36, Capacitor 8 default; 37 on Capacitor 9) | Opt-out ignored. @capacitor/status-bar overlaysWebView and backgroundColor have no effect. |
| Android WebView < 140 | env(safe-area-inset-*) wrong/0 (Chromium bug). SystemBars injects --safe-area-inset-* variables (default insetsHandling: 'css'). |
How SystemBars behaves on Android (from core source): if the page has viewport-fit=cover and WebView >= 140, insets pass through to env() and the WebView is edge-to-edge. Otherwise Capacitor pads the WebView natively so content sits between the bars and env() reports 0. --safe-area-inset-* variables carry correct values in both cases when insetsHandling is css.
Workflow
- Inspect:
index.htmlviewport meta,capacitor.config.*(ios.contentInset,android.adjustMarginsForEdgeToEdge,plugins.SystemBars,plugins.StatusBar),@capacitor/core+@capacitor/status-barversions,android/variables.gradletargetSdkVersion, global CSS that setspadding-top, UI framework (Ionic / Konsta handle insets themselves). - Decide the design: full-bleed (draw under bars, pad content) vs. contained (content between bars). Ask the user if mockups are unclear.
- Full-bleed (recommended):
viewport-fit=cover+ the CSS fallback chain below, applied once at the layout shell, not per component. - Remove legacy config: delete
android.adjustMarginsForEdgeToEdge; drop Android uses ofStatusBar.setOverlaysWebView/setBackgroundColor(keep for iOS if wanted); preferSystemBars.setStylefor icon color. - Framework check: Ionic already applies
--ion-safe-area-*; Konsta usessafeAreas. Do not double-pad. - Verify on devices (below).
Only load a reference when its topic is in play:
- references/android-edge-to-edge.md - SystemBars config, status-bar migration, nav bar color, WebView version checks
- references/css-patterns.md - layout shell, tab bars, reading insets in JS, debug overlay, resizable windows
Baseline
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
:root {
--sat: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
--sar: var(--safe-area-inset-right, env(safe-area-inset-right, 0px));
--sab: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
--sal: var(--safe-area-inset-left, env(safe-area-inset-left, 0px));
}
.app-header { padding-top: var(--sat); padding-inline: var(--sal) var(--sar); }
.app-tabbar { padding-bottom: var(--sab); padding-inline: var(--sal) var(--sar); }
The --safe-area-inset-* names are injected by Capacitor's SystemBars on Android; on iOS and web they are undefined, so the env() fallback applies.
import { SystemBars, SystemBarsStyle } from '@capacitor/core';
await SystemBars.setStyle({ style: SystemBarsStyle.Dark }); // light icons on dark background
SystemBarsStyle.Dark = light content for dark backgrounds; Light = dark content. iOS needs UIViewControllerBasedStatusBarAppearance = YES (template default).
Traps
- Missing
viewport-fit=coveris the #1 cause ofenv()= 0 on iOS and of Capacitor padding the WebView on Android. - Do not combine
ios.contentInset: 'always'with CSS safe-area padding: insets apply twice. - Do not hardcode 20/44/47/59 px status bar heights; heights differ per device, orientation, and window size.
- Insets change at runtime (rotation, iPad windowed mode, foldables, Android split screen, keyboard). Use CSS, or re-read on
resize; never cache once at startup. - On iOS the bottom inset stays while the keyboard is visible; use
max()with keyboard height (seecapacitor-keyboard). 100vhincludes the area under system bars; use100dvhor flex layout with a fixed shell.- Ionic:
ion-contentwithfullscreen+ion-headeralready pads; adding body padding shifts everything twice.
Verification
npx cap sync, run on: iPhone with Dynamic Island, iPhone SE-class (home button, small top inset), iPad (rotate + Stage Manager/windowed), Android 15/16 device or emulator in gesture and 3-button navigation, landscape.- Check Android WebView version:
adb shell dumpsys package com.google.android.webview | grep versionName(< 140 relies on injected variables). - In Safari Web Inspector /
chrome://inspect, run:
getComputedStyle(document.documentElement).getPropertyValue('--sat');
document.querySelector('meta[name=viewport]').content.includes('viewport-fit=cover');
- Confirm no element overlaps bars; tab bar taps work above the gesture bar; no double padding.
- Grep for leftovers:
grep -rn "adjustMarginsForEdgeToEdge\|setOverlaysWebView\|setBackgroundColor\|windowOptOutEdgeToEdgeEnforcement" capacitor.config.* src android/app/src/main/res 2>/dev/null
Error Handling
| Symptom / message | Cause | Fix |
|---|---|---|
Header under status bar on iOS, env() = 0 | No viewport-fit=cover | Add to viewport meta |
Android: content correct but no edge-to-edge, env() = 0 | No viewport-fit=cover or WebView < 140, so Capacitor pads natively | Add viewport-fit=cover; use --safe-area-inset-* fallback |
| Android: double gap at top | Native padding + your CSS padding with insetsHandling: 'disable' or custom MainActivity insets code | Remove custom setDecorFitsSystemWindows / inset listeners; keep SystemBars default |
StatusBar.setBackgroundColor / setOverlaysWebView no effect on Android | targetSdk 35+/36 edge-to-edge | Draw a background under the bar in CSS; use SystemBars.setStyle for icon color |
android.adjustMarginsForEdgeToEdge still in config after Capacitor 8 upgrade, margins gone | Option removed and ignored | Delete it; rely on SystemBars + CSS |
Logcat Unknown insetsHandling value '...'. Falling back to 'css'. | Invalid SystemBars.insetsHandling | Use a value listed in the current docs (css, disable; newer cores also accept native) |
| Status bar text invisible (white on white) | Style mismatch | SystemBars.setStyle({ style: SystemBarsStyle.Light }) |
| Layout jumps on first paint (Android) | SystemBars detects viewport-fit after page commit | Set plugins.SystemBars.initialViewportFitValueHint: 'cover' (in core config declarations; verify in your version) |
Resources
- System Bars API: https://capacitorjs.com/docs/apis/system-bars
- Status Bar API (Android 16 note): https://capacitorjs.com/docs/apis/status-bar
- Updating to 8.0: https://capacitorjs.com/docs/updating/8-0
- Android edge-to-edge: https://developer.android.com/develop/ui/views/layout/edge-to-edge
- WebKit viewport-fit / env(): https://webkit.org/blog/7929/designing-websites-for-iphone-x/
Tailwind CSS in Capacitor Apps
When to Use
TRIGGER when:
- Adding Tailwind to a Capacitor app (Vite, Angular, Next static export, etc.)
- Upgrading Tailwind v3 -> v4, or a v4 install produces no styles
tailwind.config.jsedits have no effect (v4 is CSS-first)- Colors / gradients broken or transparent on older iOS devices
- Safe-area, dark mode, platform-specific, or touch-target utilities
Do not use:
- Konsta UI setup/components:
konsta-ui - Ionic components and
--ion-*variables:ionic-design - SystemBars / Android edge-to-edge / status bar plugin:
safe-area-handling - Inputs hidden by keyboard:
capacitor-keyboard - Adding Capacitor to a framework:
framework-to-capacitor
Version facts (October 2026)
tailwindcss4.x islatest(4.3.x); 3.4.x onv3-lts.- v4 is configured in CSS.
tailwind.config.jsis not read unless you add@config "./tailwind.config.js";. - v4 targets Safari 16.4+, Chrome 111+, Firefox 128+ (uses
@property,color-mix(), cascade layers, oklch). - Capacitor 8 supports iOS 15+, Capacitor 9 iOS 16+. WKWebView = the device's Safari version. Devices on iOS 15.x - 16.3 render v4 styles incorrectly. Android System WebView auto-updates, so Chrome 111+ is usually met (Capacitor 9 minSdk 26).
Decision: if the iOS deployment target (or real user base) includes iOS < 16.4, ask the user: stay on Tailwind 3.4, or raise the minimum OS. Do not silently ship v4.
Workflow
Use the selected project and its installed dependencies. Package installation and migration tools execute code; limit them to the requested setup or upgrade, preserve the lockfile and existing changes, and review generated edits before running changed build scripts.
- Inspect:
npm ls tailwindcss,tailwind.config.*,postcss.config.*, bundler config, main CSS file,ios/App/App.xcodeprojIPHONEOS_DEPLOYMENT_TARGET, presence of Ionic or Konsta. - New install (below) or upgrade: references/v3-to-v4.md.
- Mobile utilities (safe areas, platform variants, touch, dark mode): references/mobile-patterns.md.
- Verify (below).
Only load a reference when its topic is in play.
Install (Vite: React, Vue, Svelte, Solid)
npm i tailwindcss @tailwindcss/vite
// vite.config.ts
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [tailwindcss() /* + framework plugin */] });
/* src/styles.css */
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
@custom-variant ios (&:where(.plt-ios, .plt-ios *));
@custom-variant android (&:where(.plt-android, .plt-android *));
@theme {
--color-brand: oklch(0.55 0.2 265);
--font-sans: system-ui, -apple-system, "Roboto", sans-serif;
}
@utility pt-safe { padding-top: env(safe-area-inset-top); }
@utility pb-safe { padding-bottom: env(safe-area-inset-bottom); }
@utility px-safe { padding-left: env(safe-area-inset-left); padding-right: env(safe-area-inset-right); }
Other toolchains: PostCSS (Angular, webpack, Next) -> npm i tailwindcss @tailwindcss/postcss and postcss.config.mjs { plugins: { "@tailwindcss/postcss": {} } }; standalone -> @tailwindcss/cli. Angular CLI 17+ reads .postcssrc.json.
// main.ts: platform class for ios:/android: variants
import { Capacitor } from '@capacitor/core';
document.documentElement.classList.add(`plt-${Capacitor.getPlatform()}`); // plt-ios | plt-android | plt-web
Add viewport-fit=cover to the viewport meta or the safe-area utilities resolve to 0.
Traps
- Content detection is automatic in v4 (respects
.gitignore). Classes innode_modulesor outside the project root need@source "../path";. Dynamic class names (`bg-${color}-500`) are never generated; map to full class strings. - v4
hover:only applies on devices with(hover: hover), so sticky hover on touch is solved by default. Useactive:for press feedback. - v4 defaults changed: border color is
currentColor,ringis 1px,shadow-sm/shadowandrounded-sm/roundedscales shifted,outline-none->outline-hidden. The upgrade tool renames most; review visually. - Ionic + Tailwind: Preflight resets Ionic typography. Import Tailwind without Preflight (
@layer theme, base, components, utilities; @import "tailwindcss/theme.css" layer(theme); @import "tailwindcss/utilities.css" layer(utilities);) or load Ionic CSS after Tailwind. - Konsta UI v5 already imports Tailwind theme pieces via
konsta/<fw>/theme.css; followkonsta-uiinstead of duplicating setup. - Do not use
100vhfor full-screen layouts; useh-dvh(v4 hasdvh/svh/lvhutilities) or a flex shell. - Android WebView < 140 reports safe-area
env()as 0; Capacitor 8 SystemBars injects--safe-area-inset-*. For Android robustness, use@utility pt-safe { padding-top: var(--safe-area-inset-top, env(safe-area-inset-top)); }(seesafe-area-handling).
Verification
npm run buildsucceeds; built CSS contains your utilities:grep -c "pt-safe" dist/assets/*.css.npx cap syncand run on: oldest supported iOS version (check colors, gradients, shadows render), current iPhone, Android 15/16.- Toggle dark mode class and OS appearance; check
ios:/android:variants by inspecting<html class>. - Leftovers after upgrade:
grep -rn "@tailwind base\|@tailwind components\|@tailwind utilities\|require('tailwindcss')" src postcss.config.* 2>/dev/nullreturns nothing.
Error Handling
| Error / symptom | Cause | Fix |
|---|---|---|
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package | v3-style PostCSS config with v4 | Use @tailwindcss/postcss (or @tailwindcss/vite) |
| No styles at all | Missing @import "tailwindcss" or bundler plugin | Add both |
Cannot apply unknown utility class in @apply | Custom class not defined via @utility, or CSS module / Vue <style> without theme reference | Define with @utility; add @reference "../styles.css"; in the scoped style |
tailwind.config.js theme changes ignored | v4 does not auto-load JS config | Move to @theme, or add @config |
| Transparent/missing colors on some iPhones | iOS < 16.4 lacks features v4 uses | Raise min iOS or stay on 3.4 |
dark: follows OS, ignores toggle | Default dark variant is media-based | Add @custom-variant dark (&:where(.dark, .dark *)); |
| Upgrade tool fails: requires Node | @tailwindcss/upgrade needs Node 20+ | Upgrade Node (Capacitor 9 needs 24+ anyway) |
Resources
- Tailwind v4 install (Vite): https://tailwindcss.com/docs/installation/using-vite
- Upgrade guide: https://tailwindcss.com/docs/upgrade-guide
- Theme variables: https://tailwindcss.com/docs/theme
- Browser support: https://tailwindcss.com/docs/compatibility
- Dark mode: https://tailwindcss.com/docs/dark-mode
Sponsors
Details
- Marketplace
- Cap-go/capgo-skills
- Source
- plugins/capacitor-ui
- Author
- Capgo
- Category
- Development
- License
- MIT
- Keywords
- capacitor, ionic, konsta, tailwind, safe-area, ipad, resizability