Repository navigation
ios27-v2.0.0
Upgrading from 1.2.1: what changes for your app?
2.0.0 keeps the Ionic theme you already use, but moves the Native UI Shell Preview and Vertical Control Area into a separate Capacitor plugin. You do not need to adopt Native UI to keep using the theme.
| How you use 1.2.1 today | What to do in 2.0.0 |
|---|---|
| Theme styles and animations only | Keep your existing theme imports, CSS/Sass paths, and animation imports. Update the theme and install Foldable alongside it; no native startup is required. |
| Native UI Shell Preview | Install @rdlabo/capacitor-native-ui directly, replace native imports and startup settings, then sync Capacitor and rebuild the native app. |
| Standalone Vertical Control Area | Move the import to the native package and replace device-layout reporting with Foldable. You can continue using the standalone startup entry. |
| Your own Web appearance with native controls | Use the native package directly. The iOS theme's styles are not required. |
Native UI and iPhone Duo support graduate from Preview to official support in 2.0.0. Only app-local extensions remain experimental.
1. Update the packages you use
For theme-only apps:
npm install @rdlabo/ionic-theme-ios27@2.0.0 @erkamyaman/capacitor-foldable@^8.3.3For apps using the theme with Native UI or Vertical Control Area:
npm install @rdlabo/ionic-theme-ios27@2.0.0 @rdlabo/capacitor-native-ui@2.0.0 @erkamyaman/capacitor-foldable@^8.3.3Keep the theme and Native UI on the same version. Declare Native UI as a direct application dependency so Capacitor can discover the plugin; the theme's transitive dependency is not sufficient for native registration. Foldable is a separate, independently versioned application dependency.
Theme-only apps can keep their current styling and animation setup. If your app uses device-layout APIs, follow step 3 as well. Installing these packages does not automatically activate native controls or connect device events.
2. Migrate native imports and settings
Skip this section if you use only theme styles and animations.
| 1.2.1 | 2.0.0 |
|---|---|
@rdlabo/ionic-theme-ios27/native |
@rdlabo/capacitor-native-ui |
@rdlabo/ionic-theme-ios27/vertical-bars |
@rdlabo/capacitor-native-ui/vertical-bars |
enableNativeUIShell() |
enableNativeUI() |
controls.toolbar |
Separate buttonGroup, button, and backButton settings |
Top-level buttonProjection |
ionic.verticalBars.buttonProjection |
buttonDefaultFill: null |
ionic.verticalBars.buttonDefaultFill: 'glass' |
verticalBarsOnly: true |
controls: 'verticalOnly' for all default selections; use per-kind values for a partial selection |
data-shell="disabled" |
data-native-ui="disabled" |
Check partial controls objects before upgrading. In 1.2.1, only fields set to true were enabled. In 2.0.0, omitted fields default to true, even inside a partial object. Simply retaining controls: { tabs: true } would also enable the other supported kinds.
To preserve a tabs-only setup:
- import { enableNativeUIShell } from '@rdlabo/ionic-theme-ios27/native';
+ import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
- const shell = await enableNativeUIShell({
- controls: { tabs: true },
+ const shell = await enableNativeUI({
+ controls: {
+ buttonGroup: false,
+ button: false,
+ backButton: false,
+ tabs: true,
+ segment: false,
+ fab: false,
+ },
});No controls setting still means all supported kinds. Use controls: false to disable default selection. Local opt-ins and explicit source declarations remain independent. buttonGroup controls grouping only; it does not enable child buttons.
The old native imports and renamed APIs have no compatibility aliases. The Native UI migration guide includes type names, opt-out classes, transition adapters, and the full settings mapping.
3. Connect device layout and rebuild native apps
Capacitor Foldable by Erkam Yaman is now our standard device-layout integration. It gives your application control over placement, inset, posture, and change events.
Replace the former theme device-reporting APIs with Foldable's initial reads and subscriptions. Apply placement with setVerticalBarsLayout and posture with applyFoldStateClasses from the theme. Native UI independently checks whether a native rail is available. See device-layout migration.
For native-enabled apps, build your Web assets, run npx cap sync, and rebuild the native app. Remove manually linked copies of the old theme Swift package. A Web-only/OTA update cannot replace the old native plugin. Check navigation, back gestures, and restored Web controls after teardown.
Ionic integration supports >=8.8.1 <10; Native UI requires Capacitor 8. Ordinary native controls require iOS 26+ and Xcode 26+. For iPhone Duo's native rails, use Capacitor 8.5+, iOS 27.1+, Xcode 27.1+, and Foldable 8.3.3 or later within version 8.
What's new
Use Native UI with your own theme—or without Ionic
Native UI is now a separate Capacitor plugin. You can keep your existing Ionic appearance, pair it with the iOS 27 theme, or use explicitly marked HTML buttons through @rdlabo/capacitor-native-ui/core. The HTML entry does not require installing Ionic.
Projection keeps the source element and its handlers in the DOM. Accepted native presentation hides the Web source from interaction and accessibility; stopping projection restores Web presentation. Unsupported markup remains on the Web.
Choose controls and placement independently
The configuration now separates three concerns:
controls: selection and grouping defaults, with independentbuttonGroup,button,backButton,tabs,segment, andfabsettings.verticalBars: rail availability and placement preferences.ionic: automatic Ionic discovery and Ionic-specific rail appearance.
Each control setting, or controls itself, accepts true, false, 'horizontalOnly', or 'verticalOnly'. Button grouping does not select its children. Local attributes and explicit source declarations can opt in independently of defaults.
Device-driven iPhone Duo layouts
Capacitor Foldable by Erkam Yaman is our standard device-layout integration. Its placement, inset, posture, and change events let your app control layout while Native UI independently checks native rail availability. Install it alongside the package you use and connect its initial state and listeners.
The theme distinguishes a half-open split pane from a fully open display: 50vw at the crease when half-open, and the theme's narrower 320px sidebar default when fully open. These are theme layout defaults, not a claim that every native app uses a fixed sidebar width.
More reliable lifecycle and clearer guidance
This release improves startup/teardown coordination, suspension and cancellation, search fallbacks, native rail popovers, and Web rail ordering. Documentation has been reorganized around theme-only apps, Ionic apps with their own appearance, and HTML apps, with dedicated configuration, appearance, and migration guides.
Experimental app-local extensions can supply SwiftUI or Compose content while keeping Web-owned state and actions. See the extensions guide.
Start here
Thank you to everyone who tested the previews and helped refine the APIs and documentation, and to Erkam Yaman for Capacitor Foldable.