Layouts and sections

CollectionLayout selects one of three native arrangements:

CollectionLayout.List();
CollectionLayout.List(grouped: true);
CollectionLayout.Grid(columns: 3, spacing: 12);
CollectionLayout.Grid(columns: 3, spacing: 12, itemAspectRatio: 1);
CollectionLayout.Carousel(
    itemWidth: 260,
    spacing: 16,
    snap: CarouselSnap.ItemPeek);

Lists use full-width rows. The grouped form uses UIKit's inset-grouped appearance. Grids divide the available width into equal columns. Carousels scroll horizontally with a fixed item width.

Set a grid's itemAspectRatio to derive its row height from the column width instead of measuring the item template. The ratio is width divided by height, so 1 produces square items and 16.0 / 9.0 produces widescreen items. The sizing cell's normal Height, MinHeight, and MaxHeight properties still constrain the derived height.

The item source and cell-template setup is covered in data and templates.

Carousel snapping

CarouselSnap.None allows free scrolling. Boundary modes stop at leading boundaries, item modes settle on individual items, ItemCentered centers one, and Page moves by a viewport at a time. The Peek variants leave part of the previous item visible to communicate that the row scrolls.

Mixed sections

A grouped collection can choose a layout for every section:

new CollectionView<Card, CardSection>
{
    GroupedItemsSource = Bind(vm => vm.Sections),
    
    ItemTemplate = static () => new CardCell(),
    SectionHeaderTemplate = static () => new SectionHeader(),
    SectionFooterTemplate = static () => new SectionFooter(),
    
    Layout = CollectionLayout.List(),
    SectionLayout = section => section.Featured
        ? CollectionLayout.Carousel(248, 8, CarouselSnap.ItemPeek)
        : CollectionLayout.List()
};

All sections share the configured ItemTemplate or ItemTemplateSelector. A selector can provide different strongly typed cell trees for the runtime item types in any section. Section header and footer templates bind to the section model.

Collection content margins

Use Padding for fixed space around the collection's content and SystemInsetEdges to add UIKit's live layout margins. These affect cells and supplementary views inside the compositional layout; the collection viewport and scroll indicators remain edge-to-edge:

new CollectionView<Card>
{
    Padding = new Thickness(0, 12, 0, 24),
    SystemInsetEdges = LayoutEdges.Horizontal,
    Header = new CollectionSummary(),
    ItemsSource = viewModel.Cards,
    ItemTemplate = static () => new CardCell()
};

Header and Footer are collection-wide views that scroll with the content. SectionHeaderTemplate and SectionFooterTemplate create one reusable supplementary view per section.

CollectionLayout.List(true) already supplies UIKit's standard horizontal system margin. SkeleKit treats that native margin as satisfying SystemInsetEdges.Horizontal instead of applying it twice; explicit Padding remains additive. Collection-wide headers and footers align to the resolved inset of the adjacent inset-grouped section.

Expandable sections

Implement IExpandableSection<TItem> to give a section an IsExpanded property. Its header receives the native disclosure treatment and toggles that state when selected. The section model must notify or otherwise participate in the collection update path used by the source.

List presentation

ShowsSeparators controls list row separators. SeparatorInsets sets leading and trailing insets; it has no effect on grid and carousel layouts.

For a grouped list with a fast-scroll index, set SectionIndexTitle to map each section to its label. IndexTitles can supply an explicit index sequence. Tapping a title scrolls to its matching section or the nearest following section.

For snapshot refreshes, selection, and programmatic scrolling, see updates and selection.