NavigationSplitView

A SwiftUI NavigationSplitView component that presents two or three columns side by side.

iOS

tvOS

Included in Expo Go

GitHub

npm

Changelog

Recommended version:

~58.0.14

Expo UI NavigationSplitView matches the official SwiftUI NavigationSplitView API and shows two or three columns side by side. The columns collapse into one when there is not enough room.

A Notes sidebar next to the detail of the selected note

Installation

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Two columns

Provide NavigationSplitView.Sidebar and NavigationSplitView.Detail. Set the title of each column with the navigationTitle modifier.

On iPhone, only the sidebar shows. On iOS 17 and later, set preferredCompactColumn to 'detail' to open the detail on tap. Pass the value from onPreferredCompactColumnChange back in so the back button works.

NavigationSplitViewExample.tsx

import {
  Button,
  Host,
  List,
  NavigationSplitView,
  type NavigationSplitViewColumn,
  Text,
} from '@expo/ui/swift-ui';
import {
  buttonStyle,
  frame,
  navigationTitle,
  padding,
} from '@expo/ui/swift-ui/modifiers';
import { useState } from 'react';

const NOTES = [
  {
    id: 'reef',
    title: 'Coral reef',
    body: 'The reef is loudest an hour after sunrise.',
  },
  {
    id: 'forest',
    title: 'Cloud forest',
    body: 'Mist arrives every afternoon, like clockwork.',
  },
  {
    id: 'dunes',
    title: 'Sand dunes',
    body: 'The ridge moves about four metres a year.',
  },
];

export default function NavigationSplitViewExample() {
  const [selectedId, setSelectedId] = useState(NOTES[0].id);
  const [compactColumn, setCompactColumn] =
    useState<NavigationSplitViewColumn>('sidebar');
  const selected =
    NOTES.find(note => note.id === selectedId) ?? NOTES[0];

  return (
    <Host style={{ flex: 1 }}>
      <NavigationSplitView
        preferredCompactColumn={compactColumn}
        onPreferredCompactColumnChange={setCompactColumn}>
        <NavigationSplitView.Sidebar>
          <List modifiers={[navigationTitle('Notes')]}>
            {NOTES.map(note => (
              <Button
                key={note.id}
                modifiers={[buttonStyle('plain')]}
                onPress={() => {
                  setSelectedId(note.id);
                  setCompactColumn('detail');
                }}>
                <Text>{note.title}</Text>
              </Button>
            ))}
          </List>
        </NavigationSplitView.Sidebar>
        <NavigationSplitView.Detail>
          <Text
            modifiers={[
              padding({ all: 24 }),
              frame({
                maxWidth: Infinity,
                maxHeight: Infinity,
                alignment: 'topLeading',
              }),
              navigationTitle(selected.title),
            ]}>
            {selected.body}
          </Text>
        </NavigationSplitView.Detail>
      </NavigationSplitView>
    </Host>
  );
}

Three columns

Add NavigationSplitView.Content between the sidebar and the detail. Set the width of a column with the navigationSplitViewColumnWidth modifier. Set how the columns share the space with the navigationSplitViewStyle modifier.

The split view picks the visible columns by default. Set columnVisibility to 'all' to show every column, or 'detailOnly' to show only the detail. When there is not enough room, it shows fewer columns. Pass the value from onColumnVisibilityChange back in. Otherwise, dragging the divider has no effect.

API

import { NavigationSplitView } from '@expo/ui/swift-ui';

Component

`NavigationSplitView`

iOS 16.0+

tvOS 16.0+

Type: React.Element<NavigationSplitViewProps>

NavigationSplitView uses the native NavigationSplitView view.

It presents a collection, a selection and a detail in one hierarchy: side by side when there is room, and stacked when there is not.

Example

<Host style={{ flex: 1 }}>
  <NavigationSplitView>
    <NavigationSplitView.Sidebar>
      <List>{items}</List>
    </NavigationSplitView.Sidebar>
    <NavigationSplitView.Detail>
      <ItemDetail item={selectedItem} />
    </NavigationSplitView.Detail>
  </NavigationSplitView>
</Host>

NavigationSplitViewProps

`children`

iOS 16.0+

tvOS 16.0+

Type: ReactNode

The columns of the split view. Provide NavigationSplitView.Sidebar and NavigationSplitView.Detail, and add NavigationSplitView.Content for a three-column layout.

`columnVisibility`

iOS 16.0+

tvOS 16.0+

Optional • Type: NavigationSplitViewVisibility • Default: 'automatic'

The columns to show. Setting it makes the value controlled: pass the value from onColumnVisibilityChange back in, otherwise dragging the divider has no effect. Leave it unset to let the split view manage its own columns.

`onColumnVisibilityChange`

iOS 16.0+

tvOS 16.0+

Optional • Type: (visibility: NavigationSplitViewVisibility) => void

Called when the visible columns change, including when the user drags the sidebar.

`onPreferredCompactColumnChange`

iOS 17.0+

Optional • Type: (column: NavigationSplitViewColumn) => void

Called when the collapsed column changes.

`preferredCompactColumn`

iOS 17.0+

Optional • Type: NavigationSplitViewColumn • Default: 'sidebar'

The column to show when the split view collapses to a single column, for example in a narrow window. Setting it makes the value controlled in the same way as columnVisibility.

Inherited props

CommonViewModifierProps

Types

`NavigationSplitViewColumn`

iOS

tvOS

Literal type: string

The column shown when the split view collapses into a single column.

Acceptable values are: 'sidebar' | 'content' | 'detail'

`NavigationSplitViewVisibility`

iOS

tvOS

Literal type: string

Acceptable values are: 'automatic' | 'all' | 'doubleColumn' | 'detailOnly'