Contents

UITableView

A view that presents data using rows in a single column.

Declaration

@MainActor class UITableView

Mentioned in

Overview

Table views in iOS display rows of vertically scrolling content in a single column. Each row in the table contains one piece of your app’s content. You can configure a table to display a single long list of rows, or you can group related rows into sections to make navigating the content easier.

When you organize rows into sections in a table, you can choose to present sections in a plain or grouped visual UITableView.Style. For example, the Contacts app displays the name of each contact in a separate row, organized into sections by the first letter of each contact’s last name. It presents the sections with a plain style. The main page of the Settings app displays the available settings organized into related sections, and presents those sections in a grouped visual style.

Tables are common in apps with data that’s highly structured or organized hierarchically. Apps that contain hierarchical data often use tables in conjunction with a navigation view controller, which facilitates navigation between different levels of the hierarchy. For example, the Settings app uses tables and a navigation controller to organize the system settings.

UITableView manages the basic appearance of the table, but your app provides the cells (UITableViewCell objects) that display the actual content. The standard cell configurations display a simple combination of text and images, but you can define custom cells that display any content you want. You can also supply header and footer views to provide additional information for groups of cells.

Add a table view to your interface

To add a table view to your interface, drag a table view controller (UITableViewController) object to your storyboard. Xcode creates a new scene that includes both the view controller and a table view, ready for you to configure and use.

Table views are data-driven, normally getting their data from a data source object that you provide. The data source object manages your app’s data and is responsible for creating and configuring the table’s cells. If the content of your table never changes, you can configure that content in your storyboard file instead.

For information about how to specify your table’s data, see Filling a table with data.

Save and restore the table’s current state

Table views support UIKit app restoration. To save and restore the table’s data, assign a nonempty value to the table view’s restorationIdentifier property. When you save its parent view controller, the table view automatically saves the index paths for the currently selected and visible rows. If the table’s data source object adopts the UIDataSourceModelAssociation protocol, the table stores the unique IDs that you provide for those items instead of their index paths.

For information about how to save and restore your app’s state information, see Preserving your app’s UI across launches.

Topics

Creating a table view

Providing the data and cells

Recycling table view cells

Recycling section headers and footers

Managing interactions with the table

Configuring the table’s appearance

Configuring cell height and layout

Configuring header and footer appearance

Customizing the separator appearance

Getting the number of rows and sections

Getting cells and section-based views

Selecting rows

Inserting, deleting, and moving rows and sections

Performing batch updates to rows and sections

Reloading the table view

Managing drag interactions

Managing drop interactions

Scrolling the table view

Putting the table into edit mode

Configuring the table index

Getting the drawing areas for the table

Working with focus

Managing context menus

Resizing self-sizing cells

Managing content-hugging behavior

Structures