List: One Reusable Row Pattern for Settings, Contacts, and Results
Learn how a design system defines one list component with clear parts, variants, states, and accessibility rules, so teams reuse it instead of rebuilding it.
In short
A list in a design system is one reusable row pattern with clear parts, variants, states and accessibility rules, so teams reuse it instead of rebuilding it.
14 min readFree
What you will learn
A list is one of the most common screens in any app. Settings pages, contact books, inbox views, and search results are all lists. In a design system, a list is a shared component. It shows a set of related items one under another, or in a grid, in the same way every time. This lesson shows you how to define that shared list: its parts, its variants, its states, and the accessibility rules that make it work for everyone. The goal is simple. Teams should reuse one list instead of building a new one for every screen.
Key words
- List
- A set of related items shown in a steady arrangement, usually stacked vertically. In this course, a list is a reusable design system component.
- Row (or list item)
- One entry in a list. A settings row, a contact row, and a search result row are all list items.
- Component
- A piece of a design that teams reuse. It has set parts and rules, so everyone builds it the same way.
- Variant
- A named version of one component, such as a single-line row or a two-line row. It is the same component with a different setup.
- Slot
- An open place inside a component where a team can put different content, such as an icon on the left or a switch on the right.
- Anatomy
- The list of parts that make up a component and where each part sits.
Read this lesson with a real app in mind. Open any mobile app with a list of settings or messages and ask yourself which parts repeat. You will see the same pattern again and again.
What is the anatomy of a list item?
Before you can reuse a list, you must agree on the parts of one row. A small, well-defined row therefore does a lot of work.
Leading element
The item on the far left. It can be an icon, a picture of a person (an avatar), or a checkbox. It is optional, so some rows have none.
Primary text
The main label of the row, such as a setting name or a person's name. It is the first thing a reader should see.
Secondary text
A smaller line under the main label that adds detail, such as a current value or a short status. Keep it short so it does not crowd the row.
Trailing element
The item on the far right. It can be an action button, a switch, a value such as a date, or a chevron (a small arrow that signals the row opens more content).
Name each part once in the system documentation and use the same name in design files and in code. A team that says "left icon" in one file and "start slot" in another will build two versions of the row without meaning to.
Name the parts by their job, not by their look. A name such as "trailing action" stays correct if the icon changes later. A name such as "red button" does not.
What variants and layout options are there?
A variant is a named version of the same list item. Material Design sets out three common list types: a single-line list, a two-line list, and a three-line list. The same parts are used in each. The only difference is how many lines of text the row holds. A contact row might use two lines (name and phone number), while a file row might use one line (file name only).
Single-line row
One primary label and nothing else. Use it when the name says everything, such as a menu item or a simple setting.
Two-line row
A primary label plus one secondary line. Use it for contacts, messages, or any row that needs a short detail.
Three-line row
A primary label plus two supporting lines. Use it only when the reader needs three pieces of information, such as an email preview with a sender, a subject, and a short snippet.
Material Design also uses subheaders to split a long list into sections. Subheaders are not rows. They are labels that sit between groups of rows, so the reader can scan the list faster.
A plain table can be split into labeled sections, and an optional index can run down the right edge for quick jumps. A grouped table places rows in boxes, and each group can have a header and a footer.
How do density and dividers work?
Density is how much space sits inside and between rows. A compact row fits more items on one screen and suits dense data, such as a long list of files. A comfortable row has more padding and suits touch screens, where people need room to tap. Define two or three density options in the system, and let each product pick one. Do not let every team invent its own spacing for each row.
Dividers are thin lines that separate one row from the next. It also separates section dividers, which mark the border between groups of rows. A clean rule for dividers keeps long lists calm and easy to scan.
Tip
Write the density and divider rules in the component's documentation as yes-or-no choices. For example: "Dividers appear between rows, never after the last row." A written rule like this is much easier for a new designer to follow than a picture alone.
What are the behavior and states?
A state is the condition a row is in at a given moment. A good list component shows each state clearly, so the reader always knows what a row will do.
Static row
A row that only shows information, such as a version number. It does not react to a tap or a click, so it should not look pressable.
Interactive row
A row that opens a page, toggles a setting, or selects an item. It needs clear feedback so people know it can be pressed.
Hover
The change a row shows when a mouse pointer rests on it. It is a desktop idea, so it should never be the only sign that a row can be used.
Focus
The outline or highlight that shows which row a keyboard user is on. Focus must be easy to see.
Selected
The state of a row that has been chosen, such as the current language in a list of languages. It often uses a check mark or a color that also has a text cue.
Disabled
A row that cannot be used right now, such as a setting locked by an admin. Keep its label readable and say why it is locked, so the reader is not left guessing.
Tip
Only interactive rows should show hover and press feedback. If a static row looks like a button, people will tap it and get nothing. This is one of the most common mistakes in list design.
How do you handle empty, loading, and long lists?
A list must also handle the moments when there is nothing to show, or too much to show at once. Plan these cases in the component rules, not screen by screen.
- 1
Empty list
Show a short message that explains why the list is empty and, where it helps, a clear next step, such as a button to add the first contact.
- 2
Loading list
Show that the list is on its way. The look of the spinner or placeholder rows is covered in a separate lesson.
- 3
Truncated list
Show a set number of rows and offer a link or button such as "See all" to open the full list. This keeps a long home screen short.
- 4
Paginated list
Split the list into pages with a clear control to move to the next page. Readers know where they are, and the screen stays fast. It suits long, numbered results such as search pages.
- 5
Infinite scroll
Load more rows as the reader reaches the bottom. It feels smooth for feeds, but readers can lose track of their place and find it hard to reach the footer. Use it only when the content has no natural end.
Add new rows at the start or end, and let the reader scroll to them when ready. Some apps show a small indicator for new items and a control that jumps to them.
Accessibility and keyboard use
Accessibility means the list works for people who use a keyboard, a screen reader, a touch screen, or large text. A list component should be built with these needs from the start. Design choices and markup both matter. Below are the main points a list rule should cover.
Semantics
A list should be marked up as a list, so a screen reader can say how many items it has and where each one begins.
Keyboard movement
For a list where one row is chosen at a time, the list should take focus and use the up and down arrow keys to move. The Orange guidelines also expect Home and End to jump to the first and last rows, and typing letters to jump to a matching row.
Focus order
Focus should move in the same order the rows appear on screen. A user who tabs through the list should never land on a hidden or out-of-order row.
Row labels
Every row action needs a clear name. A button that only shows a trash icon should still say what it deletes, such as "Delete Alex's message", so a screen reader user knows what the button does.
Selection roles
A multi-select list also needs a way to say that more than one row can be picked.
Use these rules as the test for any list you design.
Tip
Test your list by using only the keyboard for one minute. If you cannot tell which row has focus, or cannot reach a row action, the list is not ready to be shared.
Touch targets and row action labels
A touch target is the area a finger can press. Small targets cause mis-taps, which frustrate people. This gives the reader a large, easy target. When a row has several actions, such as a row with a check box and a button, each control needs its own clear target.
Set the size once in the system, not row by row. The exact size numbers belong in your platform's own guidelines, so check them before you publish a list rule.
Tip
Avoid putting many small icons inside one label. A crowded row is hard to scan and hard to tap.
Worked example: a settings screen
Let us see the list component at work on a settings screen, the kind found in many phone apps. The screen has about a dozen rows that look different on the surface, such as Wi-Fi, notifications, language, and about the app. Yet they all come from one list component. Follow the steps to see how the parts and variants cover them.
- 1
Start with one row
Take the first row, Wi-Fi. It has a leading icon of a wireless signal, a primary label that reads Wi-Fi, a secondary line that shows the network name, and a trailing chevron that signals a new page will open. These four parts are the whole row.
- 2
Name the slots
Name the open places in the component: a leading slot for the icon, a primary text slot, a secondary text slot, and a trailing slot. Each slot may be empty. Notifications has no secondary line, so its secondary slot stays empty.
- 3
Swap the trailing slot
Most rows use a chevron. A row such as Airplane Mode uses a switch in the trailing slot instead. The row shell stays the same. Only the content in the trailing slot changes. The switch itself is designed in its own lesson, so the list only holds a place for it.
- 4
Group the rows
Settings rows sit in groups. Apple's grouped table style places rows in boxes with an optional header and footer. Each group gets its own header, and the last row of each group has no divider below it.
- 5
Check the states
Tapping Wi-Fi opens a page, so the row is interactive and gets press and focus feedback. A row that only shows the app version is static and does not change when tapped. A setting locked by a device rule is disabled, and its label still reads clearly.
- 6
Count the variants
The screen uses one list component with a few settings. Single-line rows (for About), two-line rows (for Wi-Fi and Language), and switch rows (for Airplane Mode) are variants of the same shell. One component covers the whole screen, so a new settings page needs no new row design.
The lesson from this example is that the team did not build four lists. It built one row with clear slots, then picked the variant that fits each row. A designer who adds a new settings page only has to choose the slot contents and the variant.
One component, many rows
The most common question in list design is when to make a new list and when to reuse one. The answer depends on the job the row does, not on how it looks. So keep the list shell fixed, and let slots and a small number of variants carry the differences.
Tip
Ask two questions before you make a new list. Does the row keep the same order of parts? Can the differences be handled by filling a slot or choosing one variant? If both answers are yes, reuse the list.
Here is a rule that works for most teams. Make one list component with clear slots. Add a variant only when the number of lines, the density, or the interaction changes. Use slots for the content, such as a button or a chevron, rather than a new component for each option.
Check yourself
Quick check
Your team's contacts screen needs rows with an avatar, a name, and a Message button. Another screen needs rows with only text and a chevron. What should you do?
Quick check
A product shows a list of read-only account details and a list of inbox messages that open when tapped. The design team wants all rows to look the same. Which rule is correct?
Key takeaways
Define the parts once
Name the leading, primary, secondary, and trailing parts, and state which ones are optional. Use the same names in design files and documentation.
Limit the variants
Use a few variants for lines, density, and interaction. Use slots for the content that changes, and avoid a new variant for every small difference.
Design for every user
Mark up the list as a list, make focus easy to see, keep row actions clearly named, and make rows large enough to tap. Test with the keyboard before you share the component.
A good list component is quiet and predictable. The reader never has to learn a new pattern for each screen. When your team reuses one list, the product feels consistent, and each new screen takes less time to build.
Sources
- Material Design: Lists (Material Design 2 component guidance)
- Uber Base design system: List item
- Apple iOS Human Interface Guidelines: Tables (mirror of Apple's page)
- Apple Developer: Human Interface Guidelines, all components
- Orange digital accessibility guidelines: Listbox and keyboard navigation
- Telerik Design System: ListBox accessibility support
- Penpot: How to use component variants to scale your design system
- Design system best practices: Components and documentation
- Getdom: Design system components explained with real examples
- Building Accessible UI with React Aria Components
- Lego Engineering: Building accessible Select component in React
Last updated on 17 November 2026
Related lessons
- Design systemsDropdown: a floating list of options, built as a reusable component
- Design systemsPattern: Combining Components Into Reusable User Solutions
- Design systemsUser Onboarding: Reusable First-Run Patterns for Every Product Screen
- System designCloud Design Patterns: Reusable Fixes, With Strangler Fig and Sidecar
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.