Class

UITableView

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

Declaration

class UITableView : UIScrollView

Overview

Table views on iOS display a single column of vertically scrolling content, divided into rows. Each row in the table contains one piece of your app’s content. For example, the Contacts app displays the name of each contact in a separate row, and the main page of the Settings app displays the available groups of settings. 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.

Illustration showing the Contacts app and Settings app. The Contacts app uses a table to organize the user's individual contacts in a scrolling list. The Settings app displays different groups of settings in a scrolling list.

Tables are commonly used by apps whose data is 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.

Adding a Table View to Your Interface

To add a table view to your interface, drag a Table View Controller (UITableViewController) object to your storyboad. 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.

Saving and Restoring 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 its parent view controller is saved, 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

init(frame: CGRect, style: UITableView.Style)

Initializes and returns a table view object having the given frame and style.

Providing the Table's Data and Cells

var dataSource: UITableViewDataSource?

The object that acts as the data source of the table view.

var prefetchDataSource: UITableViewDataSourcePrefetching?

The object that acts as the prefetching data source for the table view, receiving notifications of upcoming cell data requirements.

protocol UITableViewDataSource

The methods adopted by the object you use to manage data and provide cells for a table view.

protocol UITableViewDataSourcePrefetching

A protocol that provides advance warning of the data requirements for a table view, allowing you to start potentially long-running data operations early.

Recycling Table View Cells

func register(UINib?, forCellReuseIdentifier: String)

Registers a nib object containing a cell with the table view under a specified identifier.

func register(AnyClass?, forCellReuseIdentifier: String)

Registers a class for use in creating new table cells.

func dequeueReusableCell(withIdentifier: String, for: IndexPath) -> UITableViewCell

Returns a reusable table-view cell object for the specified reuse identifier and adds it to the table.

func dequeueReusableCell(withIdentifier: String) -> UITableViewCell?

Returns a reusable table-view cell object located by its identifier.

Recycling Section Headers and Footers

func register(UINib?, forHeaderFooterViewReuseIdentifier: String)

Registers a nib object containing a header or footer with the table view under a specified identifier.

func register(AnyClass?, forHeaderFooterViewReuseIdentifier: String)

Registers a class for use in creating new table header or footer views.

func dequeueReusableHeaderFooterView(withIdentifier: String) -> UITableViewHeaderFooterView?

Returns a reusable header or footer view located by its identifier.

Managing Interactions with the Table

var delegate: UITableViewDelegate?

The object that acts as the delegate of the table view.

protocol UITableViewDelegate

Methods for managing selections, configuring section headers and footers, deleting and reordering cells, and performing other actions in a table view.

Configuring the Table's Appearance

var style: UITableView.Style

The style of the table view.

enum UITableView.Style

Constants for the table view styles.

var tableHeaderView: UIView?

The view that is displayed above the table's content.

var tableFooterView: UIView?

The view that is displayed below the table's content.

var backgroundView: UIView?

The background view of the table view.

Configuring Cell Height and Layout

var rowHeight: CGFloat

The default height (in points) of each row in the table view.

var estimatedRowHeight: CGFloat

The estimated height of rows in the table view.

var cellLayoutMarginsFollowReadableWidth: Bool

A Boolean value that indicates whether the cell margins are derived from the width of the readable content guide.

var insetsContentViewsToSafeArea: Bool

A Boolean value that indicates whether the table view repositions its content view to be within the current safe area.

Configuring Header and Footer Heights

var sectionHeaderHeight: CGFloat

The height of section headers in the table view.

var sectionFooterHeight: CGFloat

The height of section footers in the table view.

var estimatedSectionHeaderHeight: CGFloat

The estimated height of section headers in the table view.

var estimatedSectionFooterHeight: CGFloat

The estimated height of section footers in the table view.

Customizing the Separator Appearance

var separatorStyle: UITableViewCell.SeparatorStyle

The style for table cells used as separators.

enum UITableViewCell.SeparatorStyle

The style for cells used as separators.

var separatorColor: UIColor?

The color of separator rows in the table view.

var separatorEffect: UIVisualEffect?

The effect applied to table separators.

var separatorInset: UIEdgeInsets

The default inset of cell separators.

var separatorInsetReference: UITableView.SeparatorInsetReference

An indicator of how the separator inset value should be interpreted.

enum UITableView.SeparatorInsetReference

Constants indicating how to interpret the separator inset value of a table view.

Getting the Number of Rows and Sections

func numberOfRows(inSection: Int) -> Int

Returns the number of rows (table cells) in a specified section.

var numberOfSections: Int

The number of sections in the table view.

Getting Cells and Section-Based Views

func cellForRow(at: IndexPath) -> UITableViewCell?

Returns the table cell at the specified index path.

func headerView(forSection: Int) -> UITableViewHeaderFooterView?

Returns the header view associated with the specified section.

func footerView(forSection: Int) -> UITableViewHeaderFooterView?

Returns the footer view associated with the specified section.

func indexPath(for: UITableViewCell) -> IndexPath?

Returns an index path representing the row and section of a given table-view cell.

func indexPathForRow(at: CGPoint) -> IndexPath?

Returns an index path identifying the row and section at the given point.

func indexPathsForRows(in: CGRect) -> [IndexPath]?

An array of index paths, each representing a row enclosed by a given rectangle.

var visibleCells: [UITableViewCell]

The table cells that are visible in the table view.

var indexPathsForVisibleRows: [IndexPath]?

An array of index paths, each identifying a visible row in the table view.

Selecting Rows

var indexPathForSelectedRow: IndexPath?

An index path identifying the row and section of the selected row.

var indexPathsForSelectedRows: [IndexPath]?

The index paths representing the selected rows.

func selectRow(at: IndexPath?, animated: Bool, scrollPosition: UITableView.ScrollPosition)

Selects a row in the table view identified by index path, optionally scrolling the row to a location in the table view.

func deselectRow(at: IndexPath, animated: Bool)

Deselects a given row identified by index path, with an option to animate the deselection.

var allowsSelection: Bool

A Boolean value that determines whether users can select a row.

var allowsMultipleSelection: Bool

A Boolean value that determines whether users can select more than one row outside of editing mode.

var allowsSelectionDuringEditing: Bool

A Boolean value that determines whether users can select cells while the table view is in editing mode.

var allowsMultipleSelectionDuringEditing: Bool

A Boolean value that controls whether users can select more than one cell simultaneously in editing mode.

class let selectionDidChangeNotification: NSNotification.Name

Posted when the selected row in the posting table view changes.

Inserting, Deleting, and Moving Rows and Sections

func insertRows(at: [IndexPath], with: UITableView.RowAnimation)

Inserts rows in the table view at the locations identified by an array of index paths, with an option to animate the insertion.

func deleteRows(at: [IndexPath], with: UITableView.RowAnimation)

Deletes the rows specified by an array of index paths, with an option to animate the deletion.

func insertSections(IndexSet, with: UITableView.RowAnimation)

Inserts one or more sections in the table view, with an option to animate the insertion.

func deleteSections(IndexSet, with: UITableView.RowAnimation)

Deletes one or more sections in the table view, with an option to animate the deletion.

enum UITableView.RowAnimation

The type of animation to use when rows are inserted or deleted.

func moveRow(at: IndexPath, to: IndexPath)

Moves the row at a specified location to a destination location.

func moveSection(Int, toSection: Int)

Moves a section to a new location in the table view.

Performing Batch Updates to Rows and Sections

func performBatchUpdates((() -> Void)?, completion: ((Bool) -> Void)?)

Animates multiple insert, delete, reload, and move operations as a group.

func beginUpdates()

Begins a series of method calls that insert, delete, or select rows and sections of the table view.

func endUpdates()

Concludes a series of method calls that insert, delete, select, or reload rows and sections of the table view.

Configuring the Table Index

var sectionIndexMinimumDisplayRowCount: Int

The number of table rows at which to display the index list on the right edge of the table.

var sectionIndexColor: UIColor?

The color to use for the table view’s index text.

var sectionIndexBackgroundColor: UIColor?

The color to use for the background of the table view’s section index.

var sectionIndexTrackingBackgroundColor: UIColor?

The color to use for the table view’s index background area.

class let indexSearch: String

A constant for adding the magnifying glass icon to the section index of a table view.

Reloading the Table View

var hasUncommittedUpdates: Bool

A Boolean value indicating whether the table view's appearance contains changes that are not reflected in its data source.

func reloadData()

Reloads the rows and sections of the table view.

func reloadRows(at: [IndexPath], with: UITableView.RowAnimation)

Reloads the specified rows using a given animation effect.

func reloadSections(IndexSet, with: UITableView.RowAnimation)

Reloads the specified sections using a given animation effect.

func reloadSectionIndexTitles()

Reloads the items in the index bar along the right side of the table view.

Managing Drag Interactions

var dragDelegate: UITableViewDragDelegate?

The delegate object that manages the dragging of items from the table view.

protocol UITableViewDragDelegate

The interface for initiating drags from a table view.

var hasActiveDrag: Bool

A Boolean value indicating whether rows were lifted from the table view and have not yet been dropped.

var dragInteractionEnabled: Bool

A Boolean value indicating whether the table view supports drags and drops between apps.

Managing Drop Interactions

var dropDelegate: UITableViewDropDelegate?

The delegate object that manages the dropping of content into the table view.

protocol UITableViewDropDelegate

The interface for handling drops in a table view.

var hasActiveDrop: Bool

A Boolean value indicating whether the table view is currently tracking a drop session.

Scrolling the Table View

func scrollToRow(at: IndexPath, at: UITableView.ScrollPosition, animated: Bool)

Scrolls through the table view until a row identified by index path is at a particular location on the screen.

func scrollToNearestSelectedRow(at: UITableView.ScrollPosition, animated: Bool)

Scrolls the table view so that the selected row nearest to a specified position in the table view is at that position.

enum UITableView.ScrollPosition

The position in the table view (top, middle, bottom) to which a given row is scrolled.

Putting the Table into Edit Mode

func setEditing(Bool, animated: Bool)

Toggles the table view into and out of editing mode.

var isEditing: Bool

A Boolean value that determines whether the table view is in editing mode.

Getting the Drawing Areas for the Table

func rect(forSection: Int) -> CGRect

Returns the drawing area for a specified section of the table view.

func rectForRow(at: IndexPath) -> CGRect

Returns the drawing area for a row identified by index path.

func rectForFooter(inSection: Int) -> CGRect

Returns the drawing area for the footer of the specified section.

func rectForHeader(inSection: Int) -> CGRect

Returns the drawing area for the header of the specified section.

Remembering the Last Focused Cell

var remembersLastFocusedIndexPath: Bool

A Boolean value that indicates whether the table view should automatically return the focus to the cell at the last focused index path.