元素
SplitView
A split view shows the app’s navigation in columns: a sidebar (the sections or the lists), an optional content column
(the items of what the sidebar selects) and the detail. Each column is a NavStack of its own, so
each keeps its pages and pushes and pops on its own. On iOS, iPadOS and Mac Catalyst the columns are a
UISplitViewController’s: the sidebar floats over the content on iPadOS 26, comes in with a swipe from the edge and
with the system’s sidebar button, and the system arranges the columns as the window turns and is resized. Elsewhere
the columns stand side by side at fixed widths. Where the room is compact (a phone, a narrow window) one column shows
at a time. Which columns show is columnVisibility, a value the app owns.
import { horizontalSizeClass, type JSX, mount, Scroll, signal, Text, View } from "nsh";
import { Button, type ColumnVisibility, createNavStack, NavPage, NavStack, SplitView } from "nsh/base";
import { desktop, focusRing, hoverFill, Log, Panel, Segmented, sectionSurface, Split, tint, ui, wide } from "./palette";
// `nsh/base`'s `SplitView`: three columns, each a `NavStack` of its own. The
// app owns which columns show (`columnVisibility`); on iOS the columns are a
// UISplitViewController's, here they stand side by side, and in a phone's
// width one shows at a time, the first the visibility shows.
/** One column shows where the window is horizontally compact. */
const compact = () => horizontalSizeClass() === "compact";
const folders = ["Inbox", "Drafts", "Archive"];
const notes: Record<string, string[]> = {
Inbox: ["Design review", "Release notes", "Lunch next week"],
Drafts: ["Quarterly update"],
Archive: ["Conference badges"],
};
const visibilities: ColumnVisibility[] = ["all", "doubleColumn", "detailOnly"];
function App() {
const visibility = signal<ColumnVisibility>("all");
const folder = signal(folders[0]);
const note = signal(notes.Inbox[0]);
const events = signal<string[]>([]);
const log = (line: string) => events.set([line, ...events()].slice(0, 4));
const sidebar = createNavStack(["folders"]);
const list = createNavStack(["notes"]);
const detail = createNavStack(["note"]);
/** A row of a column: its title, its selection in the theme's tint. */
const row = (title: string, selected: boolean, onPress: () => void) => (
<Button
onPress={onPress}
accessibilityState={{ selected }}
hoverStyle={selected ? undefined : { backgroundColor: hoverFill() }}
focusVisibleStyle={focusRing()}
style={{ paddingHorizontal: 12, paddingVertical: desktop ? 8 : 12, borderRadius: 6, backgroundColor: selected ? tint(ui().accent, 0.12) : "transparent" }}
>
<Text style={{ fontSize: 14, color: ui().text, fontWeight: selected ? "600" : "400" }}>{title}</Text>
</Button>
);
/** A column's page: its title over its rows, on its surface. */
const page = (title: string, surface: string, children: JSX.Element) => (
<NavPage title={title} header={<Text style={{ paddingHorizontal: 14, paddingVertical: 10, fontSize: 13, fontWeight: "600", color: ui().text }}>{title}</Text>}>
<View style={{ flex: 1, backgroundColor: surface, borderEndWidth: 1, borderEndColor: ui().line }}>{children}</View>
</NavPage>
);
return (
<View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
<Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>split view</Text>
<Text style={{ color: ui().muted }}>
{compact() ? "Pick a folder, then a note: each brings the next column in front" : "Choose which columns show; narrow the window to see one at a time"}
</Text>
<Split
grow
width={720}
inspector={
<>
<Panel title="columnVisibility">
<Segmented options={visibilities} value={visibility()} onChange={(next) => visibility.set(next)} />
</Panel>
<Log title="events" lines={events()} minHeight={96} />
</>
}
>
<View style={{ height: wide() ? 420 : 460, ...sectionSurface(), overflow: "hidden" }}>
<SplitView
style={{ flex: 1 }}
columnVisibility={visibility()}
onColumnVisibilityChange={({ columnVisibility }) => {
visibility.set(columnVisibility);
log(`onColumnVisibilityChange: ${columnVisibility}`);
}}
sidebar={
<NavStack state={sidebar}>
{() =>
page(
"Folders",
ui().inset.backgroundColor,
<Scroll style={{ flex: 1 }} contentStyle={{ padding: 6, gap: 2 }}>
{folders.map((f) =>
row(f, folder() === f, () => {
folder.set(f);
note.set(notes[f][0]);
if (compact()) visibility.set("doubleColumn");
}),
)}
</Scroll>,
)
}
</NavStack>
}
content={
<NavStack state={list}>
{() =>
page(
folder(),
ui().card.backgroundColor,
<Scroll style={{ flex: 1 }} contentStyle={{ padding: 6, gap: 2 }}>
{notes[folder()].map((n) =>
row(n, note() === n, () => {
note.set(n);
if (compact()) visibility.set("detailOnly");
}),
)}
</Scroll>,
)
}
</NavStack>
}
detail={
<NavStack state={detail}>
{() =>
page(
note(),
ui().card.backgroundColor,
<View style={{ flex: 1, padding: 16, gap: 10 }}>
<Text style={{ fontSize: 18, fontWeight: "600", color: ui().text }}>{note()}</Text>
<Text style={{ fontSize: 14, lineHeight: 20, color: ui().muted }}>{`In ${folder()}. Each column is a NavStack of its own, so its pages stay as the others change.`}</Text>
{compact() && row("Back to the notes", false, () => visibility.set("doubleColumn"))}
</View>,
)
}
</NavStack>
}
/>
</View>
</Split>
</View>
);
}
mount(App);use nsh_base::{ColumnVisibility, button, nav_page, nav_stack, split_view, theme};
use nsh_core::prelude::*;
const MESSAGES: [&str; 2] = ["Welcome", "Release notes"];
/// A message of the inbox: a press shows it in the detail.
fn row(
title: &'static str,
selected: Signal<&'static str>,
visibility: Signal<ColumnVisibility>,
) -> impl IntoElement {
button()
.on_press(move || {
selected.set(title);
// Where one column shows, the message comes in front.
if horizontal_size_class() == SizeClass::Compact {
visibility.set(ColumnVisibility::DetailOnly);
}
})
.px_4()
.py_3()
.child(text(title).text_color(move || theme().foreground()))
}
fn mail() -> impl IntoElement {
let visibility = signal(ColumnVisibility::Automatic);
let selected = signal(MESSAGES[0]);
split_view()
.flex_1()
.column_visibility(move || Some(visibility.get()))
.on_column_visibility_change(move |next: &ColumnVisibility| visibility.set(*next))
.sidebar(nav_stack().child(nav_page().title("Inbox").child(
view()
.flex_1()
.children(MESSAGES.map(|title| row(title, selected, visibility))),
)))
.detail(nav_stack().child(
nav_page()
.title(move || SharedString::from(selected.get()))
.child(text(move || format!("{} …", selected.get())).p_4()),
))
}import { horizontalSizeClass, mount, signal, Text, View } from "nsh";
import { Button, type ColumnVisibility, createNavStack, NavPage, NavStack, SplitView } from "nsh/base";
const messages = ["Welcome", "Release notes"];
const inbox = createNavStack(["inbox"]);
const message = createNavStack(["message"]);
function App() {
const visibility = signal<ColumnVisibility>("automatic");
const selected = signal(messages[0]);
const open = (title: string) => {
selected.set(title);
// Where one column shows, the message comes in front.
if (horizontalSizeClass() === "compact") visibility.set("detailOnly");
};
return (
<SplitView
class="flex-1"
columnVisibility={visibility()}
onColumnVisibilityChange={({ columnVisibility }) => visibility.set(columnVisibility)}
sidebar={
<NavStack state={inbox}>
{() => (
<NavPage title="Inbox">
<View class="flex-1">
{messages.map((title) => (
<Button onPress={() => open(title)} class="px-4 py-3">
<Text class="text-foreground">{title}</Text>
</Button>
))}
</View>
</NavPage>
)}
</NavStack>
}
detail={
<NavStack state={message}>
{() => (
<NavPage title={selected()}>
<Text class="p-4 text-foreground">{`${selected()} …`}</Text>
</NavPage>
)}
</NavStack>
}
/>
);
}
mount(App);SplitView comes from nsh/base, nsh_base::split_view() in Rust, with
ColumnVisibility. In Rust each column is a setter that takes its stack (.sidebar(..), .content(..),
.detail(..)); in TSX each is a prop that takes a <NavStack>.
#Columns
sidebar: the first column, the app’s sections or lists.content: the middle column of three, the items of what the sidebar selects (a mailbox’s messages). Without it the view has two columns.detail: the last column, what the others select.
Each column is a NavStack: its pages, its header, its back button and its state are the stack’s, and pushing and
popping one column leaves the others as they are. The columns’ widths are the platform’s: on iOS UIKit’s, which
follow the window; elsewhere iPadOS’s defaults, the sidebar and the content column 320 points wide and the detail the
rest. The look is the app’s: the pages draw the columns’ content and backgrounds, the borders between them included.
#Which columns show
columnVisibility |
Where there is room | Where the room is compact |
|---|---|---|
"automatic" (default) |
iPadOS decides by the window’s size and orientation, keeping what the user shows; elsewhere every column | The sidebar |
"all" |
Every column | The sidebar |
"doubleColumn" |
The content and the detail; with two columns, both | The content; with two columns, the sidebar |
"detailOnly" |
The detail | The detail |
Without columnVisibility the view keeps its own value, starting from "automatic". With it, the app owns the
value and changes it in onColumnVisibilityChange({ columnVisibility }), which reports what the user or the system
shows instead: iPadOS’s sidebar button, a swipe from the edge, a press beside a column shown over the detail, going
back from a column’s first page on a phone. When the app keeps another value, the view shows the app’s again. Under
"automatic" the view keeps what the user shows; the changes iPadOS makes as the window turns or is resized belong to
"automatic" itself, so the user’s are the ones reported.
#Phones and narrow windows
Where the window is horizontally compact
(horizontalSizeClass() is "compact",
horizontal_size_class() in Rust), one column shows, the first columnVisibility shows. A selection that should
bring the detail in front sets "detailOnly" then, as the example above does.
- iOS, iPadOS and Mac Catalyst: where the window is horizontally compact (an iPhone, an iPad in Slide Over or a
narrow Split View or Stage Manager window) the split collapses into one navigation stack of the columns’ pages: the
sidebar’s, then the content’s and the detail’s, as far as
columnVisibilitygoes, with the system’s back button and swipe back between them. A page pushed on any column is pushed there. Going back from a column’s first page shows the column before, reported withonColumnVisibilityChange("detailOnly"becomes"doubleColumn"with three columns,"all"with two); a page left that is not its column’s first is popped as in any stack. Widened again, each column takes its pages back. - Android, the desktops and the web: where the window is horizontally compact (below 600 points of its width),
the column shows alone, full size. The app shows the way back to the column before: a back button in the column’s
header, or
BackHandleron Android.
On every platform each column keeps its pages and their state across both presentations.
#Props
| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
sidebar |
.sidebar(..) |
JSX.Element |
none | The first column: a NavStack. |
content |
.content(..) |
JSX.Element |
none | The middle column of three: a NavStack. Without it the view has two columns. |
detail |
.detail(..) |
JSX.Element |
none | The last column: a NavStack. |
columnVisibility |
.column_visibility(..) |
ColumnVisibility |
none | Which columns show (controlled): "automatic", "all", "doubleColumn" or "detailOnly". Without it the view keeps its own, from "automatic". |
class, style |
style methods | string, StyleProp<ViewStyle> |
none | The view itself: its size in its parent (flex-1). It stays within its bounds and takes no minimum size from its columns. |
#Events
| Event | Rust | Description |
|---|---|---|
onColumnVisibilityChange |
.on_column_visibility_change(|v: &ColumnVisibility| ..) |
{ columnVisibility }: the user or the system changed which columns show, to "all", "doubleColumn" or "detailOnly". |
#Accessibility
- Each column’s pages are its stack’s, read in column order, the sidebar first. On iOS the system’s sidebar button
and back buttons are VoiceOver’s as in any
UISplitViewController. - Where one column shows, only that column is on screen for screen readers.
See Accessibility for labels, roles and announcements in general.
#Platform notes
- iOS, iPadOS and Mac Catalyst:
UISplitViewControllerwith two or three columns, each theUINavigationControllerof itsNavStack. iPadOS 26 floats the sidebar over the content in Liquid Glass. The swipe from the edge and the sidebar button are the system’s. - Android, the desktops and the web: the columns stand side by side at fixed widths. A
DockAreais the workspace whose columns the user resizes and rearranges.