Safe Area Handling in Capacitor
Handle iPhone notch, Dynamic Island, home indicator, and Android cutouts properly.
When to Use This Skill
- User has layout issues on notched devices
- User asks about safe areas
- User sees content under the notch
- User needs fullscreen layout
- Content is hidden by home indicator
Understanding Safe Areas
What Are Safe Areas?
Safe areas are the regions of the screen not obscured by:
- iPhone: Notch, Dynamic Island, home indicator, rounded corners
- Android: Camera cutouts, navigation gestures, display cutouts
Safe Area Insets
CSS Solution
Enable Viewport Coverage
Important: viewport-fit=cover is required to access safe area insets.
Using CSS Environment Variables
Full Page Layout
Tab Bar with Safe Area
Full-Bleed Background with Safe Content
JavaScript Solution
Reading Safe Area Values
React Hook
Vue Composable
Native iOS Configuration
Status Bar Style
Extend Behind Safe Areas
Info.plist Settings
Native Android Configuration
Display Cutout Mode
Edge-to-Edge Display
AndroidManifest Configuration
Capacitor Status Bar Plugin
Installation
Usage
Common Issues and Solutions
Issue: Content Behind Notch
Solution: Add viewport-fit and safe area padding
Issue: Tab Bar Under Home Indicator
Solution: Add bottom safe area padding
Issue: Landscape Layout Broken
Solution: Handle left/right insets
Issue: Keyboard Pushes Content
Solution: Use adjustResize and handle insets dynamically
Issue: Safe Areas Not Working in WebView
Cause: Missing viewport-fit=cover
Solution:
Testing Safe Areas
iOS Simulator
- Use iPhone with notch (iPhone 14 Pro, etc.)
- Test both portrait and landscape
- Test with keyboard visible
Android Emulator
- Create emulator with camera cutout
- Test navigation gesture mode
- Test 3-button navigation mode
Preview Different Devices
Resources
- Apple Human Interface Guidelines: https://developer.apple.com/design/human-interface-guidelines/layout
- Android Display Cutouts: https://developer.android.com/develop/ui/views/layout/display-cutout
- CSS env() specification: https://drafts.csswg.org/css-env-1/
- Capacitor Status Bar: https://capacitorjs.com/docs/apis/status-bar


