Split view
Two panes side by side or one above the other, and a Handle on the line between them that a person drags, steps from the keyboard or presses to give one pane more room — and, where you allow it, to fold one pane away and bring it back.
- 类别
- 容器
- 令牌
comp.split-view- 层级
- 组合
- 构成自
- Handle
- Web
tanrei-split-viewclock_loader_40 - SwiftUI
TanreiSplitViewradio_button_unchecked - Jetpack Compose
TanreiSplitViewradio_button_unchecked - Flutter
TanreiSplitViewradio_button_unchecked - React Native
SplitViewradio_button_unchecked
Generated from docs/status/status.json, specs/split-view.spec.json
A list beside the message it opens; the list folds away with Enter or a press on the handle
A split view puts two things in one region and lets a person share the room between them: a list and the message it opens, a query and its results, a canvas and its settings. The line between the panes carries a Handle: dragged, it moves the line; moved from the keyboard, it moves it a step at a time; pressed without a drag, it folds the primary pane away and brings it back, or, where the pane cannot fold, moves the line to a share you choose and back.
The split view keeps the primary pane’s share of the region as value, in percent, tells you when a person has changed it, and gives the Handle the share as its value, so that assistive technology reads it.
On the web it is <tanrei-split-view>. The other platforms have not implemented it yet.
<!-- A list beside its detail: the list never narrower than 240 pixels, and it can fold away. -->
<tanrei-split-view id="mail" collapsible min-size="240" label="Resize the message list" style="block-size: 100dvh">
<nav slot="start" aria-label="Messages">…</nav>
<main slot="end">…</main>
</tanrei-split-view>
<!-- A query above its results. -->
<tanrei-split-view axis="vertical" value="40" label="Resize the editor" style="block-size: 600px">
<div slot="start">…</div>
<div slot="end">…</div>
</tanrei-split-view>
<script type="module">
import '@tanrei/web/components/split-view';
const mail = document.querySelector('#mail');
// Keep the person's share from one visit to the next.
mail.value = Number(localStorage.getItem('mail-list')) || 30;
mail.addEventListener('change', (e) => localStorage.setItem('mail-list', String(e.detail.value)));
</script>import { SplitView } from '@tanrei/react';
<SplitView
collapsible
value={share}
collapsed={collapsed}
minSize={240}
label="Resize the message list"
onChange={(e) => setShare(e.detail.value)}
onToggle={(e) => setCollapsed(e.detail.collapsed)}
>
<nav slot="start" aria-label="Messages">…</nav>
<main slot="end">…</main>
</SplitView>Anatomy
Anatomy
horizontal, as the web package draws it.| Part | Description |
|---|---|
1 start-pane | The pane at the start: the inline-start side while the panes stand side by side, the top while one stands above the other. It takes its size from the split and holds the product's content, clipped to it. |
2 end-pane | The pane at the end, which takes the room the start pane and the divider leave, or the other way round when it is the primary pane. |
3 divider | The hairline between the two panes, across the whole region. |
4 handle | The Handle, centred on the divider: medium, with the axis of the split, its value the primary pane's share. Its target reaches over both panes; its drawing, states, cursor and keys are the Handle's own. |
Properties
| Property | Type | Default | Description |
|---|---|---|---|
axis | horizontal | vertical | "horizontal" | Which size the split divides, as the Handle names it. horizontal: the width — the panes stand side by side and the divider is upright. vertical: the height — one pane stands above the other and the divider lies across. |
primary | start | end | "start" | Which pane the value measures and which one folds away: the start pane (a list beside its detail, a navigation beside a page) or the end pane (an inspector after a canvas). The other pane takes the rest. |
value | number | 50 | The primary pane's share of the region's size along the axis, less the divider, in percent. It is drawn held between the least and the greatest share (SPV-16) and kept as given while the region's size changes. While the pane is folded away it is the share the pane comes back at. The split view writes it as the person moves the divider; the product may set it. |
min | number | 10 | The least share of the primary pane, in percent, while it is not folded away. minSize may hold it larger (SPV-16). |
max | number | 90 | The greatest share of the primary pane, in percent: 100 less the least share the other pane keeps. maxSize may hold it smaller (SPV-16). |
minSize | number | null | The least size of the primary pane in pixels along the axis, while it is not folded away, on top of min ("the list is never narrower than 240"). Null sets none. Where the region is too small for both minSize and maxSize, minSize wins (SPV-16). |
maxSize | number | null | The greatest size of the primary pane in pixels along the axis, on top of max. Null sets none (SPV-16). |
step | number | 5 | How far one arrow key moves the divider, in percent of the region. |
largeStep | number | 20 | How far Shift with an arrow key, Page Up or Page Down moves the divider, in percent of the region. |
resetValue | number | 50 | The share a press on the Handle without a drag, Enter or Space moves the primary pane to while it cannot be folded away; the next press moves it back to where it was (SPV-7). |
collapsible | boolean | false | Lets the primary pane be folded away: by Enter or a press on the Handle, and by a drag past half its least share. Its content is then not drawn, not reachable and not read, and the divider stands at the region's edge to bring it back. |
collapsed | boolean | false | Whether the primary pane is folded away. The split view writes it as the person folds and restores the pane; the product may set it. Ignored while collapsible is false. |
label | string | "" | The Handle's accessible name, saying what the divider resizes in the product's words ("Resize the message list"); the primary pane's own heading, where it has one, is a good name. Never drawn. Required: a split view without one still works, and its Handle reports the missing name in debug builds (HDL-8). |
valueText | string | "" | Read in place of the percentage where another reading is natural ("List 320 pixels wide"), as the Handle's value text; the split view does not write it. Empty reads the percentage. |
disabled | boolean | false | Keeps both panes at their sizes: the Handle is drawn as unavailable and cannot be moved, folded or reached by Tab (HDL-15). The panes' content stays as operable as it is. |
Slots
| Slot | Description |
|---|---|
start | The content of the start pane. |
end | The content of the end pane. |
Events
| Event | Description |
|---|---|
resize | The divider moved during a drag: emitted in every frame it moves, with the primary pane's share in percent and whether the pane is folded away. |
change | The person changed the primary pane's share: once when a drag ends, and once for each key or press that moved it. Carries the new value. Not emitted when the product sets value. |
toggle | The person folded the primary pane away or brought it back: by Enter, a press on the Handle or a drag. Carries the new collapsed value. Not emitted when the product sets collapsed. |
States
Behavior
Requirements in EARS form. Every platform implementation is tested against these ids.
| ID | Requirement |
|---|---|
SPV-1 | THE split view SHALL lay out its two panes along its axis — side by side WHILE axis is horizontal, the start pane at the inline-start; one above the other WHILE axis is vertical, the start pane on top — with a divider comp.split-view.divider.width thick in comp.split-view.divider.color between them across the whole region, the primary pane its share (value, held as SPV-16 says) of the region's size along the axis less the divider and the other pane the rest; each pane SHALL clip its content to its own box and SHALL draw nothing else of its own. THE split view SHALL take the size the layout gives it; WHILE axis is vertical it divides the height the layout gives it. |
SPV-2 | THE split view SHALL place one Handle centred on its divider, at size medium and with the axis of the split, its value the primary pane's share as drawn in whole percent, its min 0 WHILE collapsible is true and the least share (SPV-16) otherwise, and its max the greatest share, as the Handle draws and exposes them (HDL-1, HDL-5, HDL-8); its target SHALL reach over both panes without moving their content, and it SHALL be in the focus order after the start pane's content and before the end pane's. THE split view SHALL relate the Handle to the primary pane as the element it controls (the window splitter pattern's controls relation), where the platform has that relation, by the means the Handle gives whoever places it to relate it to another element (HDL-26 on the web). |
SPV-3 | WHILE a drag holds the Handle (HDL-6) THE split view SHALL move the divider with the press, at every frame and without a motion of its own: the primary pane's share SHALL be the share it had when the drag began (0 WHILE it was folded away) plus the distance the Handle reports along the axis, as a share of the region less the divider, signed so that the divider moves the way the press moves, held between the least and the greatest share (SPV-16); THE split view SHALL emit resize at every frame the share drawn changes and, WHEN the drag ends and the share differs from the one the drag began with, change once with the new value. WHILE a drag lasts every embedded document in either pane SHALL take no pointer, so that the drag is not lost over it (HDL-6). |
SPV-4 | WHILE collapsible is true and a drag holds the Handle THE split view SHALL fold the primary pane away WHEN the press moves the divider past half of the least share toward the pane, and bring it back at the least share WHEN the press moves it back past that point, at every frame and without a motion of its own; a pane a drag folds away SHALL keep the share it had when the drag began as its value, to come back at; WHEN the drag ends with the pane folded away or brought back THE split view SHALL emit toggle once with the new collapsed value. |
SPV-5 | WHEN the Handle emits step (HDL-9, HDL-10) THE split view SHALL move the divider at once, without a motion: the way the key points by step percent of the region for amount one and by largeStep for amount large, held between the least and the greatest share (SPV-16); to the least share for amount limit with direction −1 (Home) and to the greatest for amount limit with direction 1 (End) whichever pane is primary, as the window splitter pattern gives Home the primary pane's smallest size and End its largest; and SHALL emit change once WHEN the share changed. A step SHALL NOT fold the pane away. WHILE the pane is folded away, a step that would give it room and Home SHALL bring it back at the least share, and End at the greatest, emitting toggle and change; a step that would take room from it SHALL change nothing. |
SPV-6 | WHILE collapsible is true, WHEN the Handle emits activate (HDL-7: a press without a drag, Enter or Space) THE split view SHALL fold the primary pane away WHILE it is shown and bring it back at the share it had before WHILE it is folded away, over comp.split-view.motion.collapse-duration with comp.split-view.motion.collapse-easing, and emit toggle once with the new collapsed value; focus SHALL stay on the Handle. |
SPV-7 | WHILE collapsible is false, WHEN the Handle emits activate THE split view SHALL move the divider to the share resetValue gives the primary pane, held between the least and the greatest share, over comp.split-view.motion.collapse-duration with comp.split-view.motion.collapse-easing, and WHEN it emits activate again before the share was changed in another way SHALL move it back to the share it had before, emitting change once each time, so that two sizes are reached without a drag (WCAG 2.5.7); WHILE the share is resetValue already and there is no share before to go back to, activate SHALL change nothing. |
SPV-8 | WHILE the primary pane is folded away THE split view SHALL give it no size and draw nothing of it, SHALL make its content unreachable by focus and hidden from assistive technology, SHALL give the other pane the whole region less the divider, and SHALL keep the divider and the Handle at the region's edge on the folded pane's side, with the Handle's value 0, so that the pane can be brought back by every input that folded it. |
SPV-9 | WHEN the product sets value or collapsed after the first frame THE split view SHALL move the divider to the new place over comp.split-view.motion.resize-duration — over comp.split-view.motion.collapse-duration WHEN collapsed changes — with comp.split-view.motion.collapse-easing, going on from the place then shown WHEN it changes again during the motion (MOT-2), and SHALL emit neither change nor toggle; THE split view SHALL draw its first frame at its value without a motion (MOT-3), and WHERE motion is reduced SHALL move the divider at once (MOT-6). |
SPV-10 | WHILE the divider moves by a motion (SPV-6, SPV-7, SPV-9) THE split view SHALL change the panes' sizes in the layout at every frame, their content laid out to the size then shown and fixed to each pane's start edge, and SHALL scroll nothing to bring a part of either into view (MOT-5). |
SPV-11 | WHEN the region's own size changes — the window or an enclosing pane is resized or turned — THE split view SHALL keep the primary pane's share and lay both panes out again at once, without a motion, and emit nothing. |
SPV-12 | WHERE the layout direction is right-to-left and axis is horizontal THE split view SHALL place the start pane at the right and the end pane at the left, and the divider SHALL still move the way a press or an arrow key points (HDL-17), so that the Right Arrow moves it to the right whichever pane is primary; it SHALL take its layout direction from where it is used, SHALL have no direction setting of its own, and SHALL NOT mirror its panes' content. |
SPV-13 | WHILE disabled is true THE split view SHALL keep both panes at their sizes and the primary pane folded or shown as it is, and its Handle SHALL take no input and no focus (HDL-15); the panes' content SHALL stay as operable as it is. |
SPV-14 | WHERE the platform draws with a person's own forced colors THE split view SHALL draw its divider in the platform's text color; the Handle draws itself as HDL-16 says. |
SPV-15 | IF min is below 0, max above 100, min above max, or value, resetValue, step or largeStep is not a finite number, or step or largeStep is not above 0, THE split view SHALL use the default of each value it cannot use, hold value between the least and the greatest share, and in debug builds report the values; IF minSize or maxSize is neither null nor a finite number of 0 or more THE split view SHALL ignore it and in debug builds report it; WHEN axis or primary names a value the split view does not define it SHALL use the default and in debug builds report it; WHILE label is empty the Handle reports its missing name (HDL-8). |
SPV-16 | THE split view SHALL hold the primary pane, while it is shown, between a least and a greatest share: the least the greater of min and minSize pixels as a share of the region's size along the axis less the divider, the greatest the lesser of max and maxSize pixels as such a share, each within 0 and 100; WHERE the region is too small for the least to stay at or below the greatest, the least SHALL win, as a least size wins over a greatest one in CSS. WHEN the region's size changes THE split view SHALL count both again and draw value held between them, keeping value as it was given (SPV-11). |
Platform name mapping
Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.
| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| Component | tanrei-split-view | TanreiSplitView | TanreiSplitView | TanreiSplitView | SplitView |
axis · Property | axis | axis | axis | axis | axis |
primary · Property | primary | primary | primary | primary | primary |
value · Property | value | value | value | value | value |
min · Property | min | range.lowerBound | valueRange.start | min | min |
max · Property | max | range.upperBound | valueRange.endInclusive | max | max |
minSize · Property | minSize | minSize | minSize | minSize | minSize |
maxSize · Property | maxSize | maxSize | maxSize | maxSize | maxSize |
step · Property | step | step | step | step | step |
largeStep · Property | largeStep | largeStep | largeStep | largeStep | largeStep |
resetValue · Property | resetValue | resetValue | resetValue | resetValue | resetValue |
collapsible · Property | collapsible | isCollapsible | collapsible | collapsible | collapsible |
collapsed · Property | collapsed | isCollapsed | collapsed | collapsed | collapsed |
label · Property | label | label | label | label | label |
valueText · Property | valueText | valueText | valueText | valueText | valueText |
disabled · Property | disabled | .disabled(_:) | enabled | enabled | disabled |
resize · Event | resize | onResize | onResize | onResize | onResize |
change · Event | change | value (Binding) | onValueChange | onChanged | onValueChange |
toggle · Event | toggle | isCollapsed (Binding) | onCollapsedChange | onCollapsedChanged | onCollapsedChange |
| Notes | <tanrei-split-view label="Resize the message list"><div slot="start">…</div><div slot="end">…</div></tanrei-split-view>. A flex row (a column while axis is vertical) in the shadow root: the start pane, the divider with the <tanrei-handle> centred on it, and the end pane; the primary pane's box is its share of the region less the divider, and the other takes the rest. The split view sets aria-controls on its Handle to the id of the primary pane's box, which the Handle moves to its separator (HDL-26). A folded pane's box is inert, and its content visibility: hidden once the fold's motion has ended. A motion is AnimatedSize on the primary pane's box. Attributes are kebab-case (min-size, max-size, large-step, reset-value, value-text). resize, change and toggle are CustomEvents that bubble and are composed, whose detail carries value and collapsed. | Drawn by Tanrei with a layout that splits a geometry reader's size, not HSplitView (macOS only, with its own divider) or NavigationSplitView (a navigation structure). | A Layout that measures the region and places the two panes and the TanreiHandle; enabled is the inverse of disabled. | A CustomMultiChildLayout of the two panes and the TanreiHandle; a folded pane is wrapped in Offstage and ExcludeSemantics. | Two Views sized by flex basis from the measured region, and the Handle between them; a folded pane is display: 'none'. |
Tokens
| Token | Aliases | Resolved (light) |
|---|---|---|
--tanrei-comp-split-view-divider-color | sys.color.outline-variant | |
--tanrei-comp-split-view-divider-width | sys.border.hairline | 1px |
--tanrei-comp-split-view-motion-collapse-duration | sys.motion.role.resize.large | 400ms |
--tanrei-comp-split-view-motion-collapse-easing | sys.motion.easing.spatial | cubic-bezier(0.2, 0, 0, 1) |
--tanrei-comp-split-view-motion-resize-duration | sys.motion.role.resize.default | 300ms |
Fixtures
Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.
horizontal
label: Resize the message list slots: start, end vertical
axis: vertical value: 60 label: Resize the editor slots: start, end primary-end
primary: end value: 30 label: Resize the inspector slots: start, end collapsed
value: 30 collapsible: true collapsed: true label: Resize the navigation slots: start, end disabled
value: 35 label: Resize the message list disabled: true slots: start, end rtl
value: 35 label: تغيير حجم قائمة الرسائل direction: rtl slots: start, end Generated from specs/split-view.spec.json, tokens/comp/split-view.tokens.json, design/tokens/
Use a split view where two things are worked on together and a person should decide how much room each gets.
| You need | Use |
|---|---|
| One box a person resizes by its edge, with nothing beside it to give room to | The resizable frame. |
| Supplementary content that comes and goes beside the page, at a width of its own | A side sheet. |
| A navigation beside the page, laid out by the page’s shell | The app shell’s navigation region. |
| Three panes or more | Two split views, one inside a pane of the other: each line is a Handle of its own. |
primary names the pane that value measures and that folds away: start (the default) for a list beside its detail or a navigation beside a page, end for an inspector after a canvas. The other pane takes the rest of the region. axis="horizontal" (the default) puts the panes side by side, the start pane at the start of the line of text — the right in a right-to-left layout; axis="vertical" puts the start pane on top.
The split view takes the size its layout gives it. A vertical one needs a height to divide: give it one, or put it in a box that has one.
value is the primary pane’s share of the region, less the divider, in percent. min and max (10 and 90 by default) keep it from going too far either way. minSize and maxSize hold the pane to pixels as well — “the list is never narrower than 240” — so that it stays readable in a wide window and a narrow one. Where the region is too small for both, minSize wins, as min-width wins over max-width in CSS. When the region’s size changes, the share you set is kept and the limits are counted again; nothing is sent.
The arrow keys move the line by step percent of the region (5), Shift with an arrow and Page Up and Page Down by largeStep (20). A drag and a key are followed at once; a fold, a press that moves the line, and a share or a fold you set move over a short motion, and at once where reduced motion is asked for.
With collapsible, Enter, Space or a press on the Handle folds the primary pane away, and the same again brings it back at the share it had. A drag past half the pane’s least share folds it too. While it is folded, its content is neither drawn nor reachable, and the line stands at the region’s edge, so that the pane can be brought back by everything that folded it. collapsed is the state; value is the share the pane comes back at.
Without collapsible, a press on the Handle moves the line to resetValue (50) and the next press back to where it was, so that a person who cannot drag still reaches two sizes with one press each.
| Event | When |
|---|---|
resize |
In every frame a drag moves the line: value, the share drawn (0 while folded), and collapsed. |
change |
Once a person has changed the share: a drag ended, a key moved the line, or a press moved it. Store it here if you keep a person’s share. |
toggle |
Once a person has folded the pane away or brought it back. |
None of them is sent for a value or collapsed you set.
- Give the Handle a name that says what it resizes:
label(“Resize the message list”). The primary pane’s own heading is a good one. - Set a least size under which the pane’s content still works, with
minSizewhere a percentage is not enough. - Keep a person’s share and fold where they will come back to them, from
changeandtoggle.
- Don’t make a pane collapsible if a person has no other way to its content when it is folded.
- Don’t draw a handle or a gutter of your own: restyle the split view’s divider and the Handle through their tokens.
- Don’t put a split view where the window is too narrow for two panes: show one at a time there, which is the page’s decision.
- Role
separator (the Handle: focusable, with a value) between two panes that have no role of their own- Labeling
- The Handle is named by label and exposes the primary pane's share in whole percent as its value (0 while the pane is folded away), with min (0 while collapsible, the least share otherwise) and the greatest share as max, valueText where given, and the primary pane as the element it controls. The panes are not landmarks of their own: a product that needs them as regions names a landmark inside each.
- Minimum target
- The hit area meets the minimum target size even when the visual size is smaller. minimum 36px · pointer 36px · spacing 8px · touch 36px
Keyboard
| Keys | Action |
|---|---|
| | Reaches the Handle between the start pane's content and the end pane's. |
| | Move the divider by step percent the way the key points; with Shift by largeStep. |
| | Move the divider by largeStep. |
| | Give the primary pane its least share (min, or minSize) or its greatest (max, or maxSize), whichever pane is primary. |
| | While collapsible: fold the primary pane away, or bring it back where it was. Otherwise: move the divider to resetValue, and back. |
Notes
- WAI-ARIA APG, Window Splitter: a focusable separator whose value is the primary pane's position, valuemin where the primary pane is smallest (typically 0), valuemax where it is largest, aria-controls naming the primary pane; arrow keys move it the way they point, Enter collapses and restores, Home gives the primary pane its smallest size and End its largest. Here Home and End stop at the least and the greatest share, and folding away is Enter's alone among the keys, so that a key held down never folds a pane by accident.
- F6 to move between panes, which the pattern lists as optional, is not taken: web browsers give F6 to their own toolbar and address bar.
- Dragging movements (WCAG 2.5.7): a press on the Handle without a drag folds and restores the pane, or moves the divider between resetValue and the share before (SPV-6, SPV-7), and the keys reach every share.
- A drag over an embedded document keeps going (HDL-6): a pane that holds an iframe does not swallow the press.
- The steps are percentages of the region, as react-resizable-panels counts them (5 for an arrow key); minSize and maxSize hold a pane to pixels on top of them, for a list that must stay readable in a wide window and a narrow one alike.
Generated from specs/split-view.spec.json, tokens/sys/measure.tokens.json
- The Handle is a focusable separator — the window splitter of the ARIA Authoring Practices — named by
label, with the primary pane’s share in whole percent as its value (0 while the pane is folded away), the least share as its minimum (0 while the pane can fold), the greatest as its maximum, and the primary pane as the element it controls. - It stands between the start pane’s content and the end pane’s in the focus order.
- The arrow keys of its axis move the line the way they point, in a right-to-left layout too; Home gives the primary pane its least share and End its greatest. Folding is Enter’s alone among the keys, so that a key held down never folds a pane by accident. F6, which the pattern lists as optional, is left to the browser, which moves to its own toolbar with it.
- Enter, Space, or a press without a drag fold and restore the pane, or move the line to
resetValueand back, so a size can be reached without dragging. - While a drag lasts, no embedded document in either pane takes the pointer, so the drag is not lost when the pointer passes over it.
- A folded pane is inert: nothing in it takes focus, and assistive technology does not read it.
- In forced-colors mode the divider takes the text color; the Handle draws itself as the Handle does.
- Give the split view its
label. Without one the Handle is still drawn and works, and a debug build reports it. - The panes are not landmarks of their own. Where a pane is a region of the page, put the landmark inside it (
<nav aria-label="Messages">,<main>). - Make sure each pane’s content works at every share you allow, from its least size up.