Split view

Columns side by side on iPad, how to build them, how a pick shows beside the list, how the sidebar shows and hides, and what iPhone and Android show.

SectionSplit viewDraftDocumented, not reviewed yet: the API can change.

On a big screen a list and its item fit side by side: the mail and the message, the settings and the section, the folders and the files. A split view puts them in columns, and SplitView builds one:

Navigation.ts

import { createNavigation, SplitView } from '@apexnative/navigation';
import { FoldersScreen } from './screens/Folders';
import { PickAFolderScreen } from './screens/PickAFolder';
import { FolderScreen } from './screens/Folder';

export const Navigation = createNavigation({
  screens: {
    Folders: FoldersScreen, // the list of folders
    PickAFolder: PickAFolderScreen, // until the user picks one
    Folder: FolderScreen, // a picked folder
  },
  root: SplitView({
    primary: 'Folders', // the sidebar
    secondary: 'PickAFolder', // beside it, before the first pick
  }),
});

On iPad, Folders shows in a sidebar and PickAFolder beside it. On iPhone the same app shows one column at a time.

This page answers:

1. What a split view is, and its columns.
2. How to build one.
3. How a pick shows beside the list.
4. How the sidebar shows and hides.
5. What a phone and a narrow window show, and Android.

What a split view is

A split view is columns side by side, each with a stack of its own. A pick in one column shows its item in the next. On iPadOS it is the system's UISplitViewController; Android has two panes of its own, see Android. Two screens that come together as one screen of a stack, such as a profile and its details, are a pair instead: see A pair or a split view.

iPadOS

primarysupplementarysecondaryinspector

primaryThe sidebar: sections, folders.

supplementaryThe middle: the items of a section.

secondaryThe item itself.

inspectoriPadOS 26: facts about the item.

compactiPhone and a narrow window: one stack instead of the columns.

'oneBesideSecondary'Side by side

'oneOverSecondary'The sidebar over the item

'secondaryOnly'The item alone

Building a split view

SplitView takes its columns, and each column names a screen of screens, as in the example above. The column beside the list needs something to show before the first pick. There it is a screen with one line:

src/screens/PickAFolder.tsx

import { Text } from 'react-native';

function PickAFolder() {
  return <Text>Pick a folder on the left</Text>;
}

Once the user picks a folder, the folder takes its place: see Showing beside the list. The columns:

• primary and secondary are needed; the others are not.
• supplementary iPadOS adds the middle column: primary: 'Folders', supplementary: 'Files', secondary: 'File'.
• inspector iPadOS 26 adds a column at the trailing edge, for facts about the item.
• compact is what an iPhone and a narrow window show: see A phone and a narrow window.

A screen alone, by its name or with Screen(…), gets a stack in each column, as in the root; the inspector is a screen on its own. Android has no middle column or inspector, and leaves them out.

Showing beside the list

A pick in a column shows its item with showInColumn, from the screen where the user picked it. The item goes into the column beside, secondary by default, in place of what the column showed:

src/screens/Folders.tsx

import { Button, FlatList } from 'react-native';
import { useNavigation } from '@apexnative/navigation';

function Folders() {
  const navigation = useNavigation();
  const folders = useFolders(); // your own data

  const open = (folderId: string) =>
    navigation.showInColumn('Folder', { props: { folderId } });

  return (
    <FlatList
      data={folders}
      renderItem={({ item }) => (
        <Button title={item.name} onPress={() => open(item.id)} />
      )}
    />
  );
}

A tap on a folder shows it beside the list, in place of PickAFolder. The column comes into view: a sidebar over it goes away. The folder is the first screen of its column's stack: a push from it opens the next screen inside that column, with the list still beside it.

With three columns, a pick in the sidebar goes to the middle, column: 'supplementary', and a pick there to secondary:

navigation.showInColumn('Files', {
  props: { folderId },
  column: 'supplementary',
});

Where there is one column, on iPhone, in a narrow window and on a narrow Android screen, the same call pushes the screen over the list, and back returns to it: the back button, and pop() from the screen (canPop() is true there). That pop animates as the system back does, whatever animations.pop. One call works everywhere.

A whole list-and-details app, step by step: List and details.

How the sidebar shows

iPadOS The split view's methods set how the sidebar shows:

Method	What it sets
displayMode(…)	How it starts: 'oneBesideSecondary' side by side, 'oneOverSecondary' the sidebar over the item, 'secondaryOnly' the item alone. With three columns, 'twoBesideSecondary' and the others.
splitBehavior(…)	How a shown sidebar shares the space: 'tile' beside, 'overlay' over, 'displace' pushing the item aside.
primaryColumn({ width, edge })	The width of the sidebar, and edge: 'trailing' to put it on the right.
displayModeButton(…), presentsWithGesture(…)	The button of the bar that shows and hides the sidebar, and the swipe that brings it.

const main = SplitView({ primary: 'Folders', secondary: 'PickAFolder' })
  .displayMode('oneBesideSecondary')
  .primaryColumn({ width: 320 });

The sidebar stays beside the item, 320 points wide.

The app shows and hides a column itself with showColumn and hideColumn, such as an inspector behind a button:

await navigation.showColumn('inspector');
await navigation.hideColumn('primary'); // the item alone

Each change, by the user or by the app, sends splitViewDisplayModeChanged (iOS only).

A phone and a narrow window

On iPhone, and on iPad when the app shares the screen in a narrow window, there is room for one column. The columns collapse into one stack, in one of two ways:

iPadOS

The split view has	One column shows
compact: 'Folders'	That layout: Folders, and showInColumn pushes over it.
No compact	The columns as one stack, with compactTopColumn on top: a pick in Folders pushes the folder, and back returns to Folders.

compact is the simpler one: the phone gets a layout of its own, as an app designed for the phone.

SplitView({
  primary: 'Folders',
  secondary: 'PickAFolder',
  compact: 'Folders', // iPhone and a narrow window
});

Android

Android The split view shows the primary and the secondary pane side by side when the width takes both: a tablet, a phone in landscape. On a narrower screen it shows the compact layout, or without it the secondary pane over the primary one. showInColumn works the same way on both platforms.

Android reads three settings: the width of the primary pane (primaryColumn({ width }), 360 by default), presentsWithGesture and compactTopColumn. The others are iOS only.

API

SplitViewOptionsTypes