Swift Default List Content Configurations

Building a list with a collection view comes down to two configuration objects working together: one decides the section's overall look, the other decides what each row contains. They're easy to mix up because both have "configuration" in the name, so it's worth separating them before looking at the presets.

UICollectionLayoutListConfiguration(appearance:) sets the section — plain, grouped, insetGrouped, or sidebar. It's the collection-view answer to UITableView.Style, with sidebar added for source-list UIs.
UIListContentConfiguration sets the cell — its presets (.cell(), .subtitleCell(), .valueCell(), .accompaniedSidebarCell(), and .header() / .footer() for supplementary views) decide where the text, secondary text, and image sit. You usually start from cell.defaultContentConfiguration(), which hands back the preset that matches the current appearance.

Assembling a list with a collection view: a list configuration (appearance: plain, grouped, insetGrouped, sidebar) feeds a list section, which feeds a compositional layout, which drives the collection view

Wiring it up is short:

// 1. The section appearance
let config = UICollectionLayoutListConfiguration(appearance: .insetGrouped)
let layout = UICollectionViewCompositionalLayout.list(using: config)

// 2. The cell content, inside a cell registration
let registration = UICollectionView.CellRegistration<UICollectionViewListCell, Item> { cell, _, item in
    var content = UIListContentConfiguration.valueCell()   // or .cell(), .subtitleCell(), .sidebarCell()…
    content.text = item.title
    content.secondaryText = item.detail
    cell.contentConfiguration = content
}

The screenshots below show the default content-configuration presets — cell, subtitleCell, valueCell, and the header/footer variants — rendered in each appearance, so you can see how the same presets shift with the section style.

Appearance plain ↴

swift default list content configuration using plain appearance in dark mode

swift default list content configuration using plain appearance in light mode

Edge-to-edge rows with sticky section headers — the everyday list. The presets here (cell, subtitleCell, valueCell, plainHeader, plainFooter) are the ones you'll reach for most.

Appearance grouped ↴

swift default list content configuration using grouped appearance in dark mode

swift default list content configuration using grouped appearance in light mode

Full-width rows gathered into spaced sections, with headers that scroll along with the content — the classic settings-style grouping.

Appearance insetGrouped ↴

swift default list content configuration using insetgrouped appearance in dark mode

swift default list content configuration using insetgrouped appearance in light mode

grouped with the rows pulled into rounded cards inset from the edges — the modern Settings look, and a good default for forms.

Appearance sidebar ↴

swift default list content configuration using sidebar appearance in dark mode

swift default list content configuration using sidebar appearance in light mode

The appearance for source lists and navigation sidebars — think the iPad Files or Notes sidebar: collapsible sections and the sidebarCell / sidebarHeader presets, which sit tighter and lighter than their plain counterparts.

Source repo used to generate the windows in the images above.