Flutter Split View Integration Guide
1. Split View Feature Overview
Flutter split view feature provides portrait/landscape adaptive split layout for applications, achieving left-right split display effects similar to tablet/foldable screen devices:
| Screen State | Layout Behavior |
|---|---|
| Landscape/Wide screen | Both sides displayed simultaneously: home page on left + detail page on right |
| Portrait/Narrow screen | Single pane display, intelligently switching between home or detail page |
| Foldable screen unfolded | Automatically switches to split layout |
| Foldable screen folded | Automatically switches to single pane layout |
Feature Highlights:
- Automatically adapts to screen size changes, no application code modification required
- Split view feature is disabled by default, enabled through configuration file
Example Application: For a complete example, see split_view_sample, which implements 8 routing schemes to test split view behavior across different routing paradigms.
Split View Support Scope:
- The split view feature currently supports both Navigator-based routing and Router-based declarative routing (including RouterDelegate, RouterConfig, go_router library, etc.)
- Router mode is implemented based on single NavigatorState + dual Overlay, unified handling at Navigator level, transparent to application layer.
- Known Limitations:
- go_router compatibility is theoretically supported, recommend thorough validation
Preview:

2. Split View Activation Instructions
Split view is disabled by default. Application only needs to place split_config.json configuration file at the specified location, and set enableWideWindowSplit or enableSquareWindowSplit to true to enable split view. SDK automatically loads this configuration file at application startup, without any initialization operations in Dart code. The configuration file can also specify home page route name, fullscreen page list and other options, see details below for each configuration item.
2.1 Configuration File Location
ohos/entry/src/main/resources/rawfile/split_config.json
2.2 Configuration File Content
{
"splitOptions": {
"enableWideWindowSplit": false,
"enableSquareWindowSplit": true,
"homePage": "/",
"fullScreenPages": ["/videoPlayer", "/imageViewer"],
"enableReducedContainerSize": true,
"supportLandscapeFullscreen": true
}
}
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
enableWideWindowSplit |
bool | false | Wide screen device split view toggle |
enableSquareWindowSplit |
bool | false | Square screen device split view toggle |
homePage |
String? | null | Home page route name, null for auto-detection |
fullScreenPages |
List | [] | List of route names for pages requiring forced fullscreen display |
enableReducedContainerSize |
bool | true | Component width displayed based on half of screen width |
supportLandscapeFullscreen |
bool | true | Whether to display fullscreen in landscape mode |
2.3 Configuration Item Details
enableWideWindowSplit
Function Description: Wide window split view toggle, controls whether to enable split layout on wide screen devices.
| Value | Effect |
|---|---|
true |
Split layout enabled on wide screen devices |
false (default) |
Split layout not enabled on wide screen devices |
Applicable Scenarios:
true: Suitable for tablets, PCs, foldable screens in unfolded state and other wide screen devices where split layout is desired in landscape modefalse: Suitable for applications that do not want to enable split view on wide screens
Trigger Conditions:
- Screen width > 600dp and height > 600dp
- Screen aspect ratio > 1.2
- Landscape orientation
enableSquareWindowSplit
Function Description: Square screen split view toggle, controls whether to enable split layout on square screen devices.
| Value | Effect |
|---|---|
true |
Split layout enabled on square screen devices |
false (default) |
Split layout not enabled on square screen devices |
Applicable Scenarios:
true: Suitable for square screen devices (such as dual-foldable screens in unfolded state) where split layout is desired on square screensfalse: Suitable for applications that do not want to enable split view on square screens
Trigger Conditions:
- Screen width > 600dp and height > 600dp
- Screen aspect ratio and inverse aspect ratio both less than 1.2
homePage
Function Description: Specifies the route name of the home page for split layout home page identification.
| Value | Effect |
|---|---|
Route name (e.g., /home) |
Explicitly specifies home page route, split view uses this page as the fixed left-side page |
| `` (default) | Auto-detect home page |
Applicable Scenarios:
- Explicitly specified route name: Suitable for applications with a clear home page, ensuring the correct page is always displayed on the left side of split view
- Auto-detection: Suitable for simple applications using Navigator-based routing, where SDK automatically determines the home page
⚠️ Important: Router mode (RouterDelegate, RouterConfig, go_router) does NOT support auto-detection. The homePage field is required for Router mode applications. Leaving it empty will cause split view to malfunction.
Navigator Mode Configuration:
Navigator mode requires that the homePage value in configuration file matches the route configuration in code, set as follows:
// Method 1: Using home parameter
return MaterialApp(
home: const HomePage(),
onGenerateRoute: (RouteSettings settings) {
switch (settings.name) {
case '/first':
return MaterialPageRoute(builder: (_) => const FirstPage(), settings: settings);
// ... other page
default:
return MaterialPageRoute(builder: (_) => const UnknownPage(), settings: settings);
}
},
// routes: { *** } routes parameter is mutually exclusive with onGenerateRoute parameter
);
// Method 2: Using initialRoute and onGenerateRoute
return MaterialApp(
initialRoute: '/splash',
onGenerateRoute: (settings) {
if (settings.name == '/home') {
return MaterialPageRoute(
settings: settings,
builder: (context) => HomePage(), // Set to the settings.name of home page in configuration file, i.e., '/home'
);
}
// ...other pages
}
);
// Method 3: Using initialRoute and routes table
return MaterialApp(
initialRoute: '/splash',
routes: {
"/home": (context) => const HomePage(), // Set to the key name of home page in configuration file, i.e., '/home'
// ...other pages
}
);
Router Mode Configuration:
Router mode (RouterDelegate, RouterConfig) uses Page objects to manage routes, where route name is determined by Page.name property:
// Page configuration in RouterDelegate / RouterConfig
pages: [
MaterialPage(
name: '/home', // Page.name determines RouteSettings.name
child: HomePage(),
),
]
go_router Mode Configuration:
go_router uses GoRoute to define routes, where route name is determined by GoRoute.name property.
Note: When a page lacks the name parameter, go_router library generates RouteSettings.name using the path parameter.
// go_router route configuration
GoRouter(
routes: [
GoRoute(
path: '/home',
name: '/home', // GoRoute.name determines RouteSettings.name, must match homePage in configuration file
builder: (context, state) => HomePage(),
),
],
)
Auto-detection Logic:
In Navigator route mode, when homePage is configured as empty, SDK automatically determines the home page in the following order:
homeparameter of MaterialApp/CupertinoApp/home,/,/indexroutes in theroutesarray- Route specified by
initialRouteparameter - If none of the above exist, an error occurs and exits
Router route mode does not support auto-detecting the home page.
Notes:
- Use
Navigator.pushNamedorMaterialPageRoute(settings: ...)with route name for navigation to correctly determine if the target page is the home page
fullScreenPages
Function Description: Specifies a list of route names for pages requiring forced fullscreen display.
| Value | Effect |
|---|---|
Route name list (e.g., ["/videoPlayer"]) |
Automatically switches to fullscreen single pane layout when entering these pages |
[] (default) |
No fullscreen pages |
Applicable Scenarios:
- Video playback pages, image viewing pages, game pages and other scenarios requiring fullscreen display
- After entering fullscreen pages, split layout is automatically disabled, and automatically restored when exiting
Notes:
- Multiple route names separated by commas
- Use
Navigator.pushNamedorMaterialPageRoute(settings: ...)with route name for navigation to correctly determine if the target page is a forced fullscreen page
enableReducedContainerSize
Function Description: Controls the width value returned by MediaQuery in split view mode.
| Value | Effect |
|---|---|
true (default) |
When split view is active, MediaQuery returns width as half of screen width |
false |
MediaQuery returns unchanged width, still the actual screen width |
Applicable Scenarios:
true: Suitable for scenarios where application components need to adapt layout based on split view width, width obtained throughMediaQuery.of(context).size.widthautomatically adapts to half of screenfalse: Suitable for scenarios where application handles width adaptation itself, or does not need MediaQuery width constraints
Technical Implementation:
- When
enableReducedContainerSize: trueand split view is active, SDK modifies width constraints through MediaQuery, making component-obtained width half of screen width - Application can obtain adapted width value through
MediaQuery.of(context).size.width
supportLandscapeFullscreen
Function Description: Controls the trigger condition for landscape fullscreen display.
| Value | Effect |
|---|---|
true (default) |
When a page is forced to landscape, split view is automatically disabled and switches to fullscreen single pane display |
false |
Split layout is maintained even when page is forced to landscape |
Applicable Scenarios:
true: Suitable for applications with pages that actively request landscape display, and where the application has already implemented layout design for landscape orientation, not wanting split view to change the landscape layout designfalse: Suitable for applications without pages that actively request landscape display, or even if actively requesting landscape still want split view to be effective
Trigger Conditions:
- Page has set forced landscape orientation (
SystemChrome.setPreferredOrientations) - And
supportLandscapeFullscreen: true
Flutter API for Requesting Display Orientation:
Flutter applications request screen orientation from the native system through SystemChrome.setPreferredOrientations. If the parameters do not include portrait orientation (i.e., only landscapeLeft/landscapeRight), it is considered that the application actively requests landscape.
Combined Usage:
- Can be used together with
fullScreenPagesconfiguration item fullScreenPagescontrols fullscreen by route name,supportLandscapeFullscreencontrols fullscreen by screen orientation
2.4 Configuration Examples
Basic Configuration (Auto-detect home page):
{
"splitOptions": {
"enableWideWindowSplit": true
}
}
Specify home page and fullscreen pages:
{
"splitOptions": {
"enableWideWindowSplit": true,
"homePage": "/home",
"fullScreenPages": ["/videoPlayer", "/imageViewer"]
}
}
3. Important Notes
3.1 Route Forwarding Execution Flow
Split view feature divides application execution into two phases, routes are managed by single NavigatorState, distributed to left and right sides through Overlay:
| Phase | Condition | Left Display | Right Display | Route Navigation Behavior |
|---|---|---|---|---|
| Phase 1 | Home page not displayed | Target page (splash page/login page etc.) | Placeholder page | Display on left Overlay, right unchanged |
| Phase 2 | Home page displayed | Home page | Detail page or placeholder page | Distribute to right Overlay for display |
Execution Flow Description:
-
Phase 1 - Home page not displayed:
- Application startup may go through splash page, login page and other intermediate pages
- All page navigations are distributed to left Overlay
- Right side keeps placeholder page unchanged
- No route forwarding
-
Phase transition - Home page displayed:
- When home page is actually displayed (navigate to home page or return to home page)
- SDK detects current route name matches configured home page route name
- Automatically switches to Phase 2 mode
-
Phase 2 - Home page displayed:
- Left side fixed displays home page
- All subsequent detail page navigations are automatically distributed to right Overlay for display
- Right side dynamically switches detail page content
Key Points:
- Only after home page is displayed, detail pages will be distributed to right side
- In splash page → login page → home page flow, the first two pages are displayed on left
- After home page is displayed, clicking on detail items will show on right side
- Route history is maintained in single NavigatorState, left and right Overlay only responsible for visual presentation
3.2 Route Configuration Scheme Selection
Split view feature supports the following route configuration schemes:
| Scheme | Routing Method | Configuration Items | Split View Compatibility | Restriction Description |
|---|---|---|---|---|
| Scheme 1 | Navigator (MaterialApp) | initialRoute + onGenerateRoute |
✅ Fully compatible | Recommended, supports complete flow |
| Scheme 2 | Navigator (MaterialApp) | initialRoute + routes |
✅ Fully compatible | Supports splash page → login page → home page flow |
| Scheme 3 | Navigator (MaterialApp) | home + onGenerateRoute |
⚠️ Partially compatible | Does not support splash/login page flow, starts directly into home page |
| Scheme 4 | Navigator (MaterialApp) | home + routes |
⚠️ Partially compatible | Does not support splash/login page flow, starts directly into home page |
| Scheme 5 | Navigator (CupertinoApp) | Same as Scheme 1-4 | ✅ Fully compatible | Equivalent to MaterialApp |
| Scheme 6 | Router (MaterialApp.router) | RouterDelegate + pages |
✅ Supported | |
| Scheme 7 | Router (MaterialApp.router) | RouterConfig |
✅ Supported | |
| Scheme 8 | Router (MaterialApp.router) | go_router library |
✅ Supported | Overlay scheme works for go_router's _CustomNavigator wrapper, recommend thorough validation |
Reason for Restriction:
homedirectly specifies the home Widget, application starts directly into home page- Cannot use
initialRoute: '/splash'to set splash page as startup page
Recommendations:
- For applications requiring splash page/login page flow, use Scheme 1 or Scheme 2
- Simple applications can directly use Scheme 3 or Scheme 4
- Router mode preferentially use Scheme 8 (GoRouter library)
3.3 Route API Usage Restrictions
3.3.1 Route settings Parameter
Must preserve the settings parameter, otherwise split view functionality is limited:
| Route Creation Method | settings | Route Name | Split View Function |
|---|---|---|---|
MaterialPageRoute(settings: settings, ...) |
✅ Present | Valid | ✅ Can identify home/fullscreen page |
MaterialPageRoute(builder: ...) |
❌ Missing | null | ⚠️ Cannot identify home/fullscreen page |
Navigator.pushNamed('/detail') |
✅ Automatic | '/detail' | ✅ Can identify home/fullscreen page |
Impact of Missing settings:
- Cannot determine if route is home page →
homePageconfiguration ineffective - Cannot determine if route is fullscreen page →
fullScreenPagesconfiguration ineffective - Split view default behavior still works, but special page identification fails
Correct Usage:
// ✅ Recommended: Use pushNamed
Navigator.pushNamed(context, '/detail');
// ✅ Recommended: Preserve settings in onGenerateRoute
onGenerateRoute: (settings) {
return MaterialPageRoute(
settings: settings, // Preserve settings
builder: (context) => DetailPage(),
);
}
// ✅ Recommended: Manually set RouteSettings
Navigator.push(
context,
MaterialPageRoute(
settings: RouteSettings(name: '/detail'),
builder: (context) => DetailPage(),
),
);
// ❌ Avoid: Not setting settings
Navigator.push(
context,
MaterialPageRoute(
builder: (context) => DetailPage(), // Cannot identify route name
),
);
3.3.2 Supported Route APIs
All Navigator route APIs are supported, split view behavior as follows:
| API | Phase 1 Behavior | Phase 2 Behavior |
|---|---|---|
push(Route) |
Push to left Overlay | Push to right Overlay |
pushNamed(String) |
Push to left Overlay | Push to right Overlay |
pushReplacement(Route) |
Replace on left Overlay | ⚠️ When initiated from home page, becomes normal push (see below) |
pushAndRemoveUntil(Route, predicate) |
Push to left Overlay and clear stack | ⚠️ When initiated from home page, becomes normal push (see below) |
pop() |
Dialog priority → right → left | Dialog priority → right → left |
canPop() |
Right priority check | Right priority check |
maybePop() |
Right priority | Right priority |
Special Behavior of pushReplacement / pushAndRemoveUntil from Home Page:
When left side displays home page, left side is fixed as home page. When calling pushReplacement or pushAndRemoveUntil from home page, since home page cannot be replaced or removed (otherwise left side would be blank), SDK will downgrade to normal push, detail page still distributed to right Overlay. This is known behavior, not a bug.
3.3.3 Unsupported Route Patterns
Does not support ternary expression for home page determination:
// ❌ Not supported: Cannot identify
MaterialApp(
home: isLoggedIn ? HomePage() : LoginPage(),
);
// ✅ Correct approach: Use initialRoute + route table
MaterialApp(
initialRoute: isLoggedIn ? '/home' : '/login',
routes: {
'/login': (context) => LoginPage(),
'/home': (context) => HomePage(),
},
);
3.4 Dialog Handling Notes
In split view mode, PopupRoute (dialogs, menus, etc.) automatically displays on the side with content:
| Right Side Status | Dialog Position | Mask Layer |
|---|---|---|
| Placeholder page | Left side | Right side covered synchronously |
| Detail page | Right side | Left side covered synchronously |
No Extra Handling Required:
- SDK automatically determines dialog position
- SDK automatically adds synchronized mask layer
- Mask layer automatically removed when dialog closes
Notes:
- Dialog push/pop triggers Overlay operations on both left and right sides
useRootNavigatorDifference:showModalBottomSheet,showMenu,showSearchand other APIs defaultuseRootNavigator: false, in split view scenario need to explicitly set totrue, to correctly display mask layer. Especially important in mixed routing scenario (such as Navigator jumping to Router page)
// ❌ Incorrect mask layer in split view
showModalBottomSheet(
context: context,
builder: (context) => SheetContent(),
);
// ✅ Need to explicitly set useRootNavigator: true
showModalBottomSheet(
context: context,
useRootNavigator: true, // Key
builder: (context) => SheetContent(),
);
3.5 Lifecycle Notes
Lifecycle Callbacks Maintain Original Behavior:
Split view mode adopts a single NavigatorState + dual Overlay approach, where route lifecycle callbacks behave consistently with normal Flutter applications:
- Routes are managed uniformly in a single NavigatorState
- RouteObserver/RouteAware usage remains unchanged, requiring no additional handling
didPush,didPop,didPopNext,didChangeNextand other callbacks trigger according to Flutter standard behavior
3.6 Page Transition Animation Notes
Split view mode supports custom PageRoute animations:
| Animation Type | Support Status |
|---|---|
| MaterialPageRoute | ✅ Supported |
| CupertinoPageRoute | ✅ Supported |
| Custom PageRoute | ✅ Supported |
| No animation route | ✅ Supported |
3.7 Back Gesture Notes
System back key/gesture back is automatically handled by SDK:
Back Priority:
- Dialog is displaying → Close dialog
- Right Overlay has poppable route → Right side pop
- Left Overlay has poppable route → Left side pop
- Both sides cannot pop → Exit application
No Extra Handling Required:
- SDK automatically intercepts
didPopRoute - Back logic executes in single NavigatorState's route history by Overlay distribution order
- Back logic executes by priority
- Application can customize back behavior through
WillPopScope
3.8 Fullscreen Page Notes
Some pages (such as video playback) require forced fullscreen:
Configuration Method:
{
"splitOptions": {
"fullScreenPages": ["/videoPlayer", "/imageViewer"]
}
}
Effects:
- Enter fullscreen page: Automatically switches to single pane layout
- Leave fullscreen page: Restores split layout
3.9 Screen Rotation/Foldable Screen Notes
SDK automatically monitors screen changes:
| Scenario | Automatic Behavior |
|---|---|
| Portrait → Landscape | Single pane → Split view |
| Landscape → Portrait | Split view → Single pane |
| Foldable screen unfolded | Single pane → Split view |
| Foldable screen folded | Split view → Single pane |
Split View Activation Conditions:
- Width > 600dp and height > 600dp
- Determined by different configuration items based on whether screen is wide or square
No Extra Handling Required:
didChangeMetrics()automatically triggers- Route stack and state fully preserved
Common Problem Troubleshooting:
| Issue | Possible Cause | Solution |
|---|---|---|
| Split view not working | Configuration file not enabled | Check enableWideWindowSplit: true |
| Home page identification error | homePage configuration error |
Configure according to Section 2.3 homePage item instructions |
| Detail page not forwarding | settings missing |
Ensure preserving settings parameter |
| Fullscreen page still in split view | fullScreenPages not configured |
Add route name to configuration list |
| RouterConfig system back key exits application | RootBackButtonDispatcher not set |
Set RootBackButtonDispatcher() in RouterConfig |
| Dialog mask layer not showing | useRootNavigator not set |
showModalBottomSheet etc. need to explicitly set useRootNavigator: true, see Section 3.4 |
| GoRouter fullscreen page not working | GoRoute.name doesn't match configuration |
Ensure GoRoute.name matches fullScreenPages configuration exactly (e.g., /video) |
pushReplacement from home page behaves abnormally |
Home page cannot be replaced | This is known behavior, SDK downgrades to normal push, see Section 3.3.2 explanation |