List View

List View

Display data in vertical lists

What it solves

A List View pattern helps teams create a reliable way to present items in a linear format that favors readability, comparison of a few attributes, and efficient scanning. It is most useful when teams need activity and inbox lists. Compared with adjacent patterns, this pattern should reduce friction without hiding the state, rules, or recovery paths people need to keep moving.

When to use

• Activity and inbox lists
• Admin records with a few fields
• Mobile-first data browsing

When to avoid

• Use a simpler view when users only need one or two values and not the full layout.
• Avoid this pattern when the task is creation or editing rather than interpretation.
• Do not force the same view onto mobile if another representation would be clearer.

Implementation workflow

1. Confirm the pattern matches the problem and constraints before copying the example. 2. Start from the anatomy and examples in references/pattern.md, then choose the smallest viable variation. 3. Apply accessibility, performance, and interaction guardrails before layering visual polish. 4. Use the testing guidance to verify behavior across keyboard, screen reader, responsive, and failure scenarios.

Accessibility guardrails

Keyboard Interaction

• [ ] Verify that list view can be completed using keyboard alone.
• [ ] Keep focus order logical when the pattern opens, updates, or reveals additional UI.
• [ ] Preserve a visible focus state that is still readable at high zoom.

Screen Reader Support

• [ ] Use semantic elements first, then add ARIA only where semantics alone are not enough.
• [ ] Announce state changes such as errors, loading, or completion in the right place and with the right politeness.
• [ ] Connect labels, hints, and status text with aria-describedby or structural headings when useful.

Visual Accessibility

• [ ] Do not rely on color alone to convey severity, completion, or selection state.

Performance guardrails

• Measure the cost of rendering the default view before adding richer adornments such as nested actions, charts, or inline filters.
• Use pagination, windowing, or progressive disclosure when the layout would otherwise render too many items at once.
• Stabilize heights and placeholder geometry so loading and data refresh states do not cause large layout shifts.

Common mistakes

Choosing the layout before the task

The Problem: Teams often pick a visually familiar pattern before confirming whether users need comparison, exploration, or scanning.

How to Fix It? Start from the user task, then map the layout to comparison, chronology, hierarchy, or overview needs.

Ignoring non-happy states

The Problem: A polished default view still feels broken when loading, empty, and error states are inconsistent.

How to Fix It? Design the data lifecycle up front, including empty, partial, stale, and failed results.

Shipping a desktop-only density model

The Problem: Large tables, dense dashboards, and heavy cards collapse quickly on small screens.

How to Fix It? Define a mobile strategy such as stacked cards, progressive disclosure, or alternate summaries before implementation.

Related patterns

• https://uxpatterns.dev/patterns/data-display/card-grid
• https://uxpatterns.dev/patterns/data-display/table
• https://uxpatterns.dev/patterns/data-display/timeline

---

For full implementation detail, examples, and testing notes, see references/pattern.md.

Pattern page: https://uxpatterns.dev/patterns/data-display/list-view

List View

Learn how to implement list views for data display. Discover best practices for list layouts, item selection, and virtual scrolling.

URL: https://uxpatterns.dev/patterns/data-display/list-view Source: apps/web/content/patterns/data-display/list-view.mdx

---

Overview

A List View pattern helps teams create a reliable way to present items in a linear format that favors readability, comparison of a few attributes, and efficient scanning. It is most useful when teams need activity and inbox lists.

Compared with adjacent patterns, this pattern should reduce friction without hiding the state, rules, or recovery paths people need to keep moving.

Use Cases

When to use:

• Activity and inbox lists
• Admin records with a few fields
• Mobile-first data browsing

When not to use:

• Use a simpler view when users only need one or two values and not the full layout.
• Avoid this pattern when the task is creation or editing rather than interpretation.
• Do not force the same view onto mobile if another representation would be clearer.

Common scenarios and examples

• Activity and inbox lists where users need a clear, repeatable interface model.
• Admin records with a few fields where users need a clear, repeatable interface model.
• Mobile-first data browsing where users need a clear, repeatable interface model.

Benefits

• Clarifies how list view should behave before implementation details begin to sprawl.
• Creates a reusable interaction model for teams who need to present items in a linear format that favors readability, comparison of a few attributes, and efficient scanning.
• Makes accessibility, edge cases, and recovery paths part of the design instead of post-launch cleanup.
• Gives product, design, and engineering a shared language for evaluating trade-offs.

Drawbacks

• It can become visually dense or noisy when too much state is shown at once.
• Responsive behavior usually needs a deliberate mobile fallback, not just smaller text.
• Loading, empty, and error states are just as important as the happy path.
• Performance work becomes visible quickly when the dataset or layout grows.

Anatomy

flowchart TB
Root[List View] --> A[List container]
Root --> B[List item]
Root --> C[Primary label]
Root --> D[Secondary metadata]
Root --> E[Item actions]

Component Structure

1. List container

• Defines the order and spacing of the items.

2. List item

• Packages the title, metadata, and actions for one record.

3. Primary label

• Provides the strongest scanning anchor.

4. Secondary metadata

• Adds status, owner, time, or category information.

5. Item actions

• Offer lightweight follow-up tasks without turning every row into a toolbar.

Summary of Components

Variations

Compact list

Shows dense rows with minimal metadata.

When to use: Use when scan speed matters most.

Detailed list

Gives each row more supporting text or status.

When to use: Use when users make decisions from the list itself.

Grouped list

Clusters rows under headings or time buckets.

When to use: Use when segmentation aids orientation.

Examples

Live Preview

Basic Implementation

<div class="demo-shell">
  <div class="card list-card">
    <ul class="list">
      <li>
        <div>
          <strong>Accessibility review</strong>
          <p class="muted">Open issues and fixes from the latest audit.</p>
        </div>
        <span class="badge">Today</span>
      </li>
      <li>
        <div>
          <strong>Design handoff checklist</strong>
          <p class="muted">Documentation work still waiting on engineering review.</p>
        </div>
        <span class="badge">Tomorrow</span>
      </li>
      <li>
        <div>
          <strong>Pattern release notes</strong>
          <p class="muted">Summary of what changed in the latest library update.</p>
        </div>
        <span class="badge">Friday</span>
      </li>
    </ul>
  </div>
</div>

What this example demonstrates

• A clear baseline implementation of list view that can be reviewed without framework-specific noise.
• Visible state, spacing, and content hierarchy that mirror the implementation guidance above.
• A small enough surface to copy into a design review or prototype before scaling the pattern up.

Implementation Notes

• Start with semantic HTML and only add JavaScript where the interaction truly requires it.
• Keep styling tokens and spacing consistent with adjacent controls or layouts.
• If the live implementation introduces async behavior, mirror those states in the code example rather than documenting them only in prose.

Best Practices

Content

Do's ✅

• Start with the questions users need answered before choosing the layout.
• Use labels, legends, and headings that explain why the data matters.
• Keep supporting metadata close to the item, card, chart, or row it describes.

Don'ts ❌

• Do not assume everyone already understands the metric, status, or sorting rule.
• Do not rely on truncation to hide critical context.
• Do not bury key actions where they only appear on hover.

Accessibility

Do's ✅

• Verify that list view can be completed using keyboard alone.
• Keep focus order logical when the pattern opens, updates, or reveals additional UI.
• Preserve a visible focus state that is still readable at high zoom.
• Use semantic elements first, then add ARIA only where semantics alone are not enough.
• Announce state changes such as errors, loading, or completion in the right place and with the right politeness.

Don'ts ❌

• Do not remove focus styles without a visible replacement.
• Do not depend on placeholder or helper text that disappears before the user can act on it.
• Do not assume pointer, touch, and assistive technologies will all interact with the pattern the same way.

Visual Design

Do's ✅

• Use hierarchy to separate primary values from supporting context.
• Reserve space for loading and empty states to avoid layout jumps.
• Design density levels intentionally for desktop and mobile.

Don'ts ❌

• Do not use decorative chrome that competes with the data itself.
• Do not make all rows, cards, or panels look equally important when priorities differ.
• Do not overload a single view with every possible control.

Layout & Positioning

Do's ✅

• Preserve scannability as the viewport shrinks.
• Keep filters, summaries, and data visibly connected.
• Choose stable ordering and grouping rules so users can build muscle memory.

Don'ts ❌

• Do not let controls jump around between breakpoints.
• Do not hide essential data behind horizontal scrolling without a fallback.
• Do not treat empty or zero states as an afterthought.

Common Mistakes & Anti-Patterns 🚫

Choosing the layout before the task

The Problem: Teams often pick a visually familiar pattern before confirming whether users need comparison, exploration, or scanning.

How to Fix It? Start from the user task, then map the layout to comparison, chronology, hierarchy, or overview needs.

---

Ignoring non-happy states

The Problem: A polished default view still feels broken when loading, empty, and error states are inconsistent.

How to Fix It? Design the data lifecycle up front, including empty, partial, stale, and failed results.

---

Shipping a desktop-only density model

The Problem: Large tables, dense dashboards, and heavy cards collapse quickly on small screens.

How to Fix It? Define a mobile strategy such as stacked cards, progressive disclosure, or alternate summaries before implementation.

Data Flow

• Start by defining the source of truth for the dataset, then map how filters, sorting, and view state transform that dataset before render.
• Keep loading, empty, and partial states in the same data flow model as the populated state so the view does not need separate ad hoc logic.
• When the pattern supports drilling into detail, keep the transition between overview and detail explicit so users understand what changed.

Performance

• Measure the cost of rendering the default view before adding richer adornments such as nested actions, charts, or inline filters.
• Use pagination, windowing, or progressive disclosure when the layout would otherwise render too many items at once.
• Stabilize heights and placeholder geometry so loading and data refresh states do not cause large layout shifts.

Usability Considerations

• Test whether people can answer the intended question in under a few seconds; if not, the layout may be too dense or too vague.
• Make sort, filter, and grouping rules visible whenever they change the order or subset of data.
• Give users a clear path back to a simpler or more detailed view when one layout cannot answer every question.

Accessibility

Keyboard Interaction

• [ ] Verify that list view can be completed using keyboard alone.
• [ ] Keep focus order logical when the pattern opens, updates, or reveals additional UI.
• [ ] Preserve a visible focus state that is still readable at high zoom.

Screen Reader Support

• [ ] Use semantic elements first, then add ARIA only where semantics alone are not enough.
• [ ] Announce state changes such as errors, loading, or completion in the right place and with the right politeness.
• [ ] Connect labels, hints, and status text with aria-describedby or structural headings when useful.

Visual Accessibility

• [ ] Do not rely on color alone to convey severity, completion, or selection state.
• [ ] Test the pattern at 200% zoom and with reduced motion enabled.
• [ ] Ensure touch targets remain comfortable on mobile and coarse pointers.

Testing Guidelines

Functional Testing

• [ ] Verify the default, loading, error, and success states for list view.
• [ ] Test the primary action and the obvious recovery action in the same run.
• [ ] Confirm that state survives refresh, navigation, or retry in the way users would expect.

Accessibility Testing

• [ ] Run keyboard-only checks and at least one screen reader pass on the final implementation.
• [ ] Validate headings, labels, and announcement behavior with real content rather than lorem ipsum.
• [ ] Check color contrast and focus visibility in both default and stressed states.

Edge Cases

• [ ] Test empty, long, duplicated, and unexpectedly formatted content.
• [ ] Check behavior on narrow screens, zoomed layouts, and slower networks.
• [ ] Verify that optimistic or asynchronous states reconcile correctly after a failure.

Frequently Asked Questions

Related Patterns

Resources

References

• WCAG 2.2 - Accessibility baseline for keyboard support, focus management, and readable state changes.
• WAI-ARIA Authoring Practices - Reference patterns for keyboard behavior, semantics, and assistive technology support.

Guides

• web.dev: Rendering on the Web - Rendering tradeoffs for data-rich pages, dashboards, and result-heavy views.

Articles

• Stephanie Walter: Designing complex data tables - Design considerations for dense tables, column behavior, and analytical workflows.
• Smashing Magazine: Checklist for cards - A practical review of content hierarchy, action density, and card sizing.

NPM Packages

• `react-virtuoso` - Virtualized list and table components for large feeds and long result sets.
• `masonic` - Virtualized masonry grid for card-dense layouts and galleries.
• `@tanstack/react-virtual` - Virtualization primitives for large lists, tables, and feeds.