UX Patterns Guide
UI + UX Data Display And Exploration established

Master-detail

Provide an adaptive master-detail layout with a source list, detail destination, synchronized selected item, empty detail placeholder, stacked detail navigation, Back to list behavior, side-by-side presentation on wider screens, and preserved list, selection, filter, scroll, edit, and route state across layout changes.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • Users repeatedly choose items from a collection and work with a substantial detail destination.
  • Wide layouts should keep list context visible while detail is active.
  • Narrow layouts need stacked navigation between list and detail with preserved state.
  • The selected item and detail state can be keyed by stable IDs and synchronized reliably.

Avoid when

  • The detail is only a short metadata summary.
  • The content is temporary supplemental information with close behavior.
  • The main task is dense row comparison or cell editing.
  • Users rarely return to the list after opening detail.
  • Responsive transitions cannot preserve selection, history, or unsaved detail work.

Problem it prevents

Users need to explore a set of items and inspect or work with one item's full detail repeatedly, but separate pages make context switching slow, a small details panel cannot hold the full destination, and a fixed layout can fail across phones, tablets, foldables, and desktop windows.

Test the behavior

Open the interactive example when you need it

The full lab is intentionally loaded on request. That keeps this reading page fast while preserving the strong and weak states, keyboard checks, and failure scenarios.

In the lab you can
  • switch between strong UI, weak UI, strong UX, and weak UX;
  • trigger required, empty, loading, error, and recovery states;
  • inspect keyboard and accessibility expectations beside the demo.
Launch Master-detail in the lab
Pattern anatomy

What a strong implementation has to make clear

User need

The source items are conversations, orders, tickets, files, contacts, tasks, articles, cases, settings sections, media, or records.

Pattern promise

Provide an adaptive master-detail layout with a source list, detail destination, synchronized selected item, empty detail placeholder, stacked detail navigation, Back to list behavior, side-by-side presentation on wider screens, and preserved list, selection, filter, scroll, edit, and route state across layout changes.

Required state

Wide default state with master list, selected item, and detail pane visible together.

Recovery path

The detail pane shows an object that is not selected in the master list.

Access contract

Name the master and detail regions with headings that describe the collection and the selected item.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • An inbox shows conversations in the left pane and the selected message thread in the right pane on desktop, then shows either the conversation list or selected thread with Back to inbox on phone.
  • A customer order app keeps the order list, selected order highlight, order detail heading, shipment timeline, and Back to orders path synchronized across side-by-side and stacked layouts.
  • A user selects a case, scrolls its detail history, narrows the window to stacked mode, goes back to the case list, selects another case, and widening the window shows the new selected case beside the list.
  • A keyboard user moves through the master list, opens a detail, returns to the same list position, and the selected row remains tied to the detail heading.
Weak implementation

Vague, hidden, hard to recover from

  • Selecting an order highlights one list item while the detail pane still shows a previous order.
  • On mobile, tapping a list item replaces the list with detail but provides no return path, selected-item label, or preserved list position.
  • A user filters the master list after opening detail and the layout keeps showing a hidden case without saying it no longer matches the filter.
  • A user rotates a tablet and the app resets to the first list item, discarding the detail draft and scroll position.
UI guidance
  • Render a master-detail layout with a primary list or source pane, a detail pane that names the selected item, a visible selected-item indicator, and a clear empty-detail state when no item owns the detail.
  • Adapt the same content relationship between side-by-side panes on wider screens and stacked list/detail navigation on narrower screens, with visible Back to list or equivalent return control in stacked mode.
UX guidance
  • Use master-detail when users move repeatedly between a collection of items and full detail content, and the detail can act as a navigable destination rather than only a small inspector.
  • Preserve selected item, detail scroll or edit state, list position, filters, and return path as users select items, open detail, go back, and resize or rotate the viewport.
Implementation contract

What the implementation must handle

States

  • Wide default state with master list, selected item, and detail pane visible together.
  • Wide empty-detail state with a prompt when no item is selected.
  • Stacked list state where only the master list is visible.
  • Stacked detail state with selected-item heading and Back to list control.

Interaction

  • Selecting an item in the master list updates the selected marker and detail heading to the same object.
  • In side-by-side mode, selection can update detail without hiding the master list.
  • In stacked mode, opening detail moves to the detail view and Back to list returns to the same master list position and filters.
  • Changing viewport size preserves the current selected object and chooses whether list, detail, or both panes should be visible based on the active navigation state.

Accessibility

  • Name the master and detail regions with headings that describe the collection and the selected item.
  • Expose selected state in the master list and keep it synchronized with the detail heading.
  • Provide a visible and accessible Back to list control in stacked detail mode.
  • Move focus intentionally when opening stacked detail and return focus to the selected master item when going back.

Review

  • What is the master collection, and which exact selected item owns the detail right now?
  • Can the detail stand as a navigable destination, or is it only an inspector suited to details panel?
  • What happens to selection, list position, detail scroll, and draft state when the layout switches between stacked and side-by-side?
  • How do users return from detail to the list on compact screens?
Evidence trail

Source-backed claims behind this guidance

Microsoft List/details pattern

Microsoft Learn - checked

Supports list pane, details pane, selected-item update, stacked style, side-by-side style, and adaptive breakpoints.

Android Canonical layouts: List-detail

Android Developers - checked

Supports canonical list-detail behavior, compact versus expanded layout, state preservation, and back navigation to the list.

Material Design Canonical layouts

Google Material Design - checked

Supports list-detail as a canonical adaptive layout distinct from feed and supporting-pane layouts.

Full agent/debug reference

Problem Context

  • The source items are conversations, orders, tickets, files, contacts, tasks, articles, cases, settings sections, media, or records.
  • The detail content is substantial enough to need its own heading, body, local actions, history, comments, edits, or route state.
  • Users often switch between adjacent items while keeping enough context to know where the current detail came from.
  • The same product must work in narrow stacked mode and wider side-by-side mode without losing selection or navigation history.

Selection Rules

  • Choose master-detail when list selection opens or owns a full detail destination and the layout must coordinate source and detail state.
  • Choose master-detail when wide screens should show list and detail together while narrow screens should show either list or detail with a return path.
  • Use details panel when the detail is a concise adjacent inspector and does not need navigable page-like behavior.
  • Use list view when users only need to scan and act on rows without a coordinated detail destination.
  • Use window splitter when users need to resize panes; pair it with master-detail only if the list-detail behavior is also defined.
  • Use drawer or sheet when detail is temporary, opened by command, and should close after a side task.
  • Use preview panel when the detail is primarily rendered document, media, or file preview rather than full object work.
  • Use full-page navigation when side-by-side context adds little value or the detail is too deep for a shared layout.
  • Avoid master-detail when no stable selected item exists.
  • Avoid master-detail when responsive transitions would lose detail state, list position, or back navigation.

Required States

  • Wide default state with master list, selected item, and detail pane visible together.
  • Wide empty-detail state with a prompt when no item is selected.
  • Stacked list state where only the master list is visible.
  • Stacked detail state with selected-item heading and Back to list control.
  • Selection changed state where list highlight, detail heading, route state, and local actions update together.
  • Filtered-away selected item state with explanation, clear-filter path, or selection replacement.
  • Viewport widened, narrowed, rotated, or folded state preserving list position, selected item, and detail state.
  • Loading, failed detail, deleted item, permission-limited detail, unsaved detail draft, and unavailable detail states.
  • Back navigation, browser history, deep link, and no-selection return states.
  • Multiple-pane or tertiary detail state when the layout can add supporting content on large screens.

Interaction Contract

  • Selecting an item in the master list updates the selected marker and detail heading to the same object.
  • In side-by-side mode, selection can update detail without hiding the master list.
  • In stacked mode, opening detail moves to the detail view and Back to list returns to the same master list position and filters.
  • Changing viewport size preserves the current selected object and chooses whether list, detail, or both panes should be visible based on the active navigation state.
  • If the selected item becomes filtered, deleted, or unavailable, the detail pane explains the state instead of showing stale content.
  • Detail-local actions state which selected item they affect and do not silently act on a different master row.
  • Deep links can open the detail directly and still provide a path to the relevant master list when the product supports it.
  • Unsaved changes, scroll position, focus, and local detail state survive layout changes or trigger explicit review before being discarded.

Implementation Checklist

  • Define the master collection, selected-item ID, detail route or state owner, empty-detail rule, and compact versus expanded layout breakpoints.
  • Render a visible selected state in the master list and repeat the selected object name or ID in the detail heading.
  • Implement stacked navigation with Back to list, browser history, focus return, and preserved list scroll position.
  • Implement side-by-side mode with synchronized selection, detail refresh, and an empty placeholder when no selection exists.
  • Persist selected item, filters, sort order, list scroll, detail scroll, local edits, and focus across viewport changes.
  • Handle loading, failed detail fetch, deleted item, permission-limited detail, filtered-away item, no results, and direct deep link states.
  • Keep resizable splitters, drawers, previews, and inspectors separate from the master-detail ownership model unless deliberately combined.
  • Test keyboard selection, screen reader pane names, Back behavior, browser history, mobile rotation, tablet resize, long titles, localization, zoom, and stale-detail prevention.

Common Generated-UI Mistakes

  • Calling a small metadata inspector master-detail when the detail cannot act as a destination.
  • Forgetting the stacked mobile return path from detail back to the master list.
  • Showing stale detail after selection, filter, delete, permission, or refresh changes.
  • Resetting selection, filters, draft edits, or scroll position when the viewport crosses a breakpoint.
  • Using a splitter as the only implementation while leaving selected-item ownership and navigation history undefined.
  • Showing an unrelated default detail on wide screens before the user has selected an item.
  • Embedding full primary editing in the detail without unsaved-change protection across selection changes.
  • Letting list and detail actions target different objects because they are keyed by visible index instead of stable item ID.

Critique Questions

  • What is the master collection, and which exact selected item owns the detail right now?
  • Can the detail stand as a navigable destination, or is it only an inspector suited to details panel?
  • What happens to selection, list position, detail scroll, and draft state when the layout switches between stacked and side-by-side?
  • How do users return from detail to the list on compact screens?
  • What should the wide layout show when there is no selection, a hidden selection, or a deleted item?
  • Would list view, details panel, preview panel, drawer, window splitter, table, or full-page route better fit the task?
Accessibility
  • Name the master and detail regions with headings that describe the collection and the selected item.
  • Expose selected state in the master list and keep it synchronized with the detail heading.
  • Provide a visible and accessible Back to list control in stacked detail mode.
  • Move focus intentionally when opening stacked detail and return focus to the selected master item when going back.
  • Announce detail changes, filtered-away selection, loading, failed detail, and no-selection states when they update dynamically.
  • Keep DOM order, visual order, and keyboard order understandable across stacked and side-by-side layouts.
  • Protect unsaved detail changes before changing selection or leaving detail in stacked mode.
  • Do not use color, pane position, or viewport width alone to communicate which item owns the detail.
Keyboard Behavior
  • Tab reaches master controls, the selected master item, detail heading or first detail action, Back to list, and any layout controls in predictable order.
  • Arrow keys or list commands may move selection within the master list when the list component supports that behavior.
  • Enter or Space on a master item opens or selects the item and updates the detail according to the current layout mode.
  • In stacked mode, Back to list returns focus to the selected master item or the closest available item.
  • Browser Back returns from stacked detail to the master list when the detail created a navigation entry.
  • Selection changes with unsaved detail edits trigger review before replacing the detail.
  • Escape does not discard detail or navigate back unless the product explicitly defines that shortcut.
  • Viewport changes do not move focus unexpectedly into a hidden pane.
Variants
  • Inbox master-detail
  • Order list-detail
  • Contact list-detail
  • Settings master-detail
  • Case review master-detail
  • Document list-detail
  • Media browser list-detail
  • Adaptive two-pane master-detail
  • Stacked mobile master-detail
  • Three-pane master-detail
  • Master-detail with detail draft
  • Master-detail with filterable list

Verification

Source trail checked:

Saved items