List

Usage

Use a list to present a series of related items in a single, ordered column, whether that's settings, links, files, or menu items. Group items under a header when it helps users understand what they have in common, and add a footer when a short explanation would help. Keep each row focused on one thing, and lean on the built-in accessories, like toggles, badges, and trailing icons, so rows stay consistent across the app.

Types

Lists are built from a container plus a set of row types. You compose a list by choosing the container options, then adding the rows you need.

List container

The list container provides the shared structure for a group, with an optional header and footer, while the rows inside carry the content and actions.

Header types

Default header

A standard title above the list group.

Collapsible header

Users can expand and collapse the list group.

Row types

The kinds of rows a list can hold, from content rows to action rows.

Content row

The standard row with a label and optional description.

Default

Label only.

Truncated description

Label + truncated description that is visible for a single line.

Full description

Label + full description.

Inline link

Label + full description + inline text link. The link is placed on a new line below the description rather than at the end of it.

Button row

A row that behaves like an action, with primary, destructive, and disabled states.

Accessories

The optional elements that attach to a row to extend what it does, such as: toggles, badges, leading icons, trailing icons, or a secondary label.

Leading accessories

Placed before the label, at the start of the row.

Icon

An icon that represents the row’s content or category, giving users a quick visual cue.

Favicon

A site favicon, used when the row points to a specific website or destination.

Trailing accessories

Placed after the label, at the end of the row. Each row uses the one that matches its purpose.

Right label

A secondary value, such as the current setting or a selected option.

Trailing icon

An icon used for navigation (like a chevron), a related action or status.

Badge

A small indicator for a count or status.

Toggle

An on or off switch for a setting the user can change right in the row.

List style

Island

When the list is inset from the screen edges, all four corners are rounded, so the list reads as a group. Islands suit grouped settings and content.

Full-width

When the list spans the full width of the screen. Full-width lists suit dense, screen-filling layouts.

Older OS considerations

The corner radius of island lists differs by OS version.

iOS 26

Uses a 26px corner radius, which gives the list a rounder, more pronounced curve in line with the current design language.

Older OS versions

Uses a 10px corner radius, which keeps the corners subtler and matches the earlier system styling.

Behavior and interaction

• Tapping a row triggers its action, whether that is navigating or toggling a setting. It’s accessory signals what will happen.
• A row with a toggle changes state right in place, without leaving the list.
• A collapsible header expands or folds its group when tapped, so users can hide sections they don't need.
• Destructive button rows stand out in red, so users can tell them apart from ordinary actions before they tap.
• Disabled rows read as inactive and don't respond to taps until they become available again.
• Long lists scroll with the screen, and dividers keep the rows visually separated as they pass.
• Labels and descriptions are editable text. Keep labels short so rows stay easy to scan, and use descriptions only when a row genuinely needs the extra context.

Positioning

• Rows are separated by dividers, and a group can carry a header above it and a footer below.
• Lists scroll with the screen when the content runs longer than the viewport.
• A collapsible header lets users fold a section away, which keeps long lists manageable.

Changelog