Class

UITableView

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

Declaration

@interface 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

- initWithFrame:style:

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

Providing the Table's Data and Cells

dataSource

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

prefetchDataSource

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

UITableViewDataSource

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

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

- registerNib:forCellReuseIdentifier:

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

- registerClass:forCellReuseIdentifier:

Registers a class for use in creating new table cells.

- dequeueReusableCellWithIdentifier:forIndexPath:

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

- dequeueReusableCellWithIdentifier:

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

Recycling Section Headers and Footers

- registerNib:forHeaderFooterViewReuseIdentifier:

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

- registerClass:forHeaderFooterViewReuseIdentifier:

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

- dequeueReusableHeaderFooterViewWithIdentifier:

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

Managing Interactions with the Table

delegate

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

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

style

The style of the table view.

UITableViewStyle

Constants for the table view styles.

tableHeaderView

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

tableFooterView

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

backgroundView

The background view of the table view.

Configuring Cell Height and Layout

rowHeight

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

estimatedRowHeight

The estimated height of rows in the table view.

cellLayoutMarginsFollowReadableWidth

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

insetsContentViewsToSafeArea

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

sectionHeaderHeight

The height of section headers in the table view.

sectionFooterHeight

The height of section footers in the table view.

estimatedSectionHeaderHeight

The estimated height of section headers in the table view.

estimatedSectionFooterHeight

The estimated height of section footers in the table view.

Customizing the Separator Appearance

separatorStyle

The style for table cells used as separators.

UITableViewCellSeparatorStyle

The style for cells used as separators.

separatorColor

The color of separator rows in the table view.

separatorEffect

The effect applied to table separators.

separatorInset

The default inset of cell separators.

separatorInsetReference

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

UITableViewSeparatorInsetReference

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

Getting the Number of Rows and Sections

- numberOfRowsInSection:

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

numberOfSections

The number of sections in the table view.

Getting Cells and Section-Based Views

- cellForRowAtIndexPath:

Returns the table cell at the specified index path.

- headerViewForSection:

Returns the header view associated with the specified section.

- footerViewForSection:

Returns the footer view associated with the specified section.

- indexPathForCell:

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

- indexPathForRowAtPoint:

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

- indexPathsForRowsInRect:

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

visibleCells

The table cells that are visible in the table view.

indexPathsForVisibleRows

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

Selecting Rows

indexPathForSelectedRow

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

indexPathsForSelectedRows

The index paths representing the selected rows.

- selectRowAtIndexPath:animated:scrollPosition:

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

- deselectRowAtIndexPath:animated:

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

allowsSelection

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

allowsMultipleSelection

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

allowsSelectionDuringEditing

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

allowsMultipleSelectionDuringEditing

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

UITableViewSelectionDidChangeNotification

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

Inserting, Deleting, and Moving Rows and Sections

- insertRowsAtIndexPaths:withRowAnimation:

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

- deleteRowsAtIndexPaths:withRowAnimation:

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

- insertSections:withRowAnimation:

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

- deleteSections:withRowAnimation:

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

UITableViewRowAnimation

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

- moveRowAtIndexPath:toIndexPath:

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

- moveSection:toSection:

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

Performing Batch Updates to Rows and Sections

- performBatchUpdates:completion:

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

- beginUpdates

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

- endUpdates

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

Configuring the Table Index

sectionIndexMinimumDisplayRowCount

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

sectionIndexColor

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

sectionIndexBackgroundColor

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

sectionIndexTrackingBackgroundColor

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

UITableViewIndexSearch

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

Reloading the Table View

hasUncommittedUpdates

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

- reloadData

Reloads the rows and sections of the table view.

- reloadRowsAtIndexPaths:withRowAnimation:

Reloads the specified rows using a given animation effect.

- reloadSections:withRowAnimation:

Reloads the specified sections using a given animation effect.

- reloadSectionIndexTitles

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

Managing Drag Interactions

dragDelegate

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

UITableViewDragDelegate

The interface for initiating drags from a table view.

hasActiveDrag

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

dragInteractionEnabled

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

Managing Drop Interactions

dropDelegate

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

UITableViewDropDelegate

The interface for handling drops in a table view.

hasActiveDrop

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

Scrolling the Table View

- scrollToRowAtIndexPath:atScrollPosition:animated:

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

- scrollToNearestSelectedRowAtScrollPosition:animated:

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

UITableViewScrollPosition

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

Putting the Table into Edit Mode

- setEditing:animated:

Toggles the table view into and out of editing mode.

editing

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

Getting the Drawing Areas for the Table

- rectForSection:

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

- rectForRowAtIndexPath:

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

- rectForFooterInSection:

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

- rectForHeaderInSection:

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

Remembering the Last Focused Cell

remembersLastFocusedIndexPath

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

Relationships

Inherits From