iOS Developer Library

Developer

UIKit Framework Reference UITableViewDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

UITableViewDelegate

The delegate of a UITableView object must adopt the UITableViewDelegate protocol. Optional methods of the protocol allow the delegate to manage selections, configure section headings and footers, help to delete and reorder cells, and perform other actions.

Many methods of the UITableViewDelegate protocol take NSIndexPath objects as parameters and return values. UIKit declares a category on NSIndexPath that enables you to get the represented row index (row property) and section index (section property), and to construct an index path from a given row index and section index (indexPathForRow:inSection: method). Because rows are located within their sections, you usually must evaluate the section index number before you can identify the row by its index number.

Inheritance


Not Applicable

Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.
  • Asks the delegate for the height to use for a row in a specified location.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, heightForRowAtIndexPath indexPath: NSIndexPath) -> CGFloat

    Objective-C

    - (CGFloat)tableView:(UITableView *)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object requesting this information.

    indexPath

    An index path that locates a row in tableView.

    Return Value

    A nonnegative floating-point value that specifies the height (in points) that row should be.

    Discussion

    The method allows the delegate to specify rows with varying heights. If this method is implemented, the value it returns overrides the value specified for the rowHeight property of UITableView for the given row.

    There are performance implications to using tableView:heightForRowAtIndexPath: instead of the rowHeight property. Every time a table view is displayed, it calls tableView:heightForRowAtIndexPath: on the delegate for each of its rows, which can result in a significant performance problem with table views having a large number of rows (approximately 1000 or more). See also tableView:estimatedHeightForRowAtIndexPath:.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Asks the delegate for the estimated height of a row in a specified location.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, estimatedHeightForRowAtIndexPath indexPath: NSIndexPath) -> CGFloat

    Objective-C

    - (CGFloat)tableView:(UITableView *)tableView estimatedHeightForRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object requesting this information.

    indexPath

    An index path that locates a row in tableView.

    Return Value

    A nonnegative floating-point value that estimates the height (in points) that row should be. Return UITableViewAutomaticDimension if you have no estimate.

    Discussion

    Providing an estimate the height of rows can improve the user experience when loading the table view. If the table contains variable height rows, it might be expensive to calculate all their heights and so lead to a longer load time. Using estimation allows you to defer some of the cost of geometry calculation from load time to scrolling time.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Asks the delegate to return the level of indentation for a row in a given section.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, indentationLevelForRowAtIndexPath indexPath: NSIndexPath) -> Int

    Objective-C

    - (NSInteger)tableView:(UITableView *)tableView indentationLevelForRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object requesting this information.

    indexPath

    An index path locating the row in tableView.

    Return Value

    Returns the depth of the specified row to show its hierarchical position in the section.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Tells the delegate the table view is about to draw a cell for a particular row.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, willDisplayCell cell: UITableViewCell, forRowAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)tableView:(UITableView *)tableView willDisplayCell:(UITableViewCell *)cell forRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object informing the delegate of this impending event.

    cell

    A table-view cell object that tableView is going to use when drawing the row.

    indexPath

    An index path locating the row in tableView.

    Discussion

    A table view sends this message to its delegate just before it uses cell to draw a row, thereby permitting the delegate to customize the cell object before it is displayed. This method gives the delegate a chance to override state-based properties set earlier by the table view, such as selection and background color. After the delegate returns, the table view sets only the alpha and frame properties, and then only when animating rows as they slide in or out.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    tableView:cellForRowAtIndexPath: (UITableViewDataSource)
    prepareForReuse (UITableViewCell)

  • Asks the delegate for the actions to display in response to a swipe in the specified row. (required)

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, editActionsForRowAtIndexPath indexPath: NSIndexPath) -> [AnyObject]?

    Objective-C

    - (NSArray *)tableView:(UITableView *)tableView editActionsForRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table view object requesting this information.

    indexPath

    The index path of the row.

    Return Value

    An array of UITableViewRowAction objects representing the actions for the row. Each action you provide is used to create a button that the user can tap.

    Discussion

    Use this method when you want to provide custom actions for one of your table rows. When the user swipes horizontally in a row, the table view moves the row content aside to reveal your actions. Tapping one of the action buttons executes the handler block stored with the action object.

    If you do not implement this method, the table view displays the standard accessory buttons when the user swipes the row.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate for the type of standard accessory view to use as a disclosure control for the specified row.

    Deprecation Statement

    Use the accessory-view and accessory-type properties (for both normal and editing modes) of the UITableViewCell class when configuring table-view cells.

    Declaration

    Objective-C

    - (UITableViewCellAccessoryType)tableView:(UITableView *)tableView accessoryTypeForRowWithIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object requesting the accessory-view type.

    indexPath

    An index path locating the row in tableView.

    Return Value

    A constant identifying a type of standard accessory view. For details, see the "€œConstants” section in UITableViewCell Class Reference.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 3.0.

  • Tells the delegate that the user tapped the accessory (disclosure) view associated with a given row.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, accessoryButtonTappedForRowWithIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)tableView:(UITableView *)tableView accessoryButtonTappedForRowWithIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object informing the delegate of this event.

    indexPath

    An index path locating the row in tableView.

    Discussion

    The delegate usually responds to the tap on the disclosure button (the accessory view) by displaying a new view related to the selected row. This method is not called when an accessory view is set for the row at indexPath.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Tells the delegate that the table view is about to go into editing mode.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, willBeginEditingRowAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)tableView:(UITableView *)tableView willBeginEditingRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object providing this information.

    indexPath

    An index path locating the row in tableView.

    Discussion

    This method is called when the user swipes horizontally across a row; as a consequence, the table view sets its editing property to YEStrue (thereby entering editing mode) and displays a Delete button in the row identified by indexPath. In this "€œswipe to delete"€ mode the table view does not display any insertion, deletion, and reordering controls. This method gives the delegate an opportunity to adjust the application'€™s user interface to editing mode. When the table exits editing mode (for example, the user taps the Delete button), the table view calls tableView:didEndEditingRowAtIndexPath:.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Tells the delegate that the table view has left editing mode.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, didEndEditingRowAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)tableView:(UITableView *)tableView didEndEditingRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object providing this information.

    indexPath

    An index path locating the row in tableView.

    Discussion

    This method is called when the table view exits editing mode after having been put into the mode by the user swiping across the row identified by indexPath. As a result, a Delete button appears in the row; however, in this "€œswipe to delete"€ mode the table view does not display any insertion, deletion, and reordering controls. When entering this "€œswipe to delete"€ editing mode, the table view sends a tableView:willBeginEditingRowAtIndexPath: message to the delegate to allow it to adjust its user interface.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Asks the delegate for the editing style of a row at a particular location in a table view.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, editingStyleForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCellEditingStyle

    Objective-C

    - (UITableViewCellEditingStyle)tableView:(UITableView *)tableView editingStyleForRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object requesting this information.

    indexPath

    An index path locating a row in tableView.

    Return Value

    The editing style of the cell for the row identified by indexPath.

    Discussion

    This method allows the delegate to customize the editing style of the cell located atindexPath. If the delegate does not implement this method and the UITableViewCell object is editable (that is, it has its editing property set to YEStrue), the cell has the UITableViewCellEditingStyleDelete style set for it.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Changes the default title of the delete-confirmation button.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, titleForDeleteConfirmationButtonForRowAtIndexPath indexPath: NSIndexPath) -> String!

    Objective-C

    - (NSString *)tableView:(UITableView *)tableView titleForDeleteConfirmationButtonForRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object requesting this information.

    indexPath

    An index-path object locating the row in its section.

    Return Value

    A localized string to used as the title of the delete-confirmation button.

    Discussion

    By default, the delete-confirmation button, which appears on the right side of the cell, has the title of “Delete”. The table view displays this button when the user attempts to delete a row, either by swiping the row or tapping the red minus icon in editing mode. You can implement this method to return an alternative title, which should be localized.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Asks the delegate whether the background of the specified row should be indented while the table view is in editing mode.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, shouldIndentWhileEditingRowAtIndexPath indexPath: NSIndexPath) -> Bool

    Objective-C

    - (BOOL)tableView:(UITableView *)tableView shouldIndentWhileEditingRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object requesting this information.

    indexPath

    An index-path object locating the row in its section.

    Return Value

    YEStrue if the background of the row should be indented, otherwise NOfalse.

    Discussion

    If the delegate does not implement this method, the default is YEStrue. This method is unrelated to tableView:indentationLevelForRowAtIndexPath:.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Asks the delegate to return a new index path to retarget a proposed move of a row.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, targetIndexPathForMoveFromRowAtIndexPath sourceIndexPath: NSIndexPath, toProposedIndexPath proposedDestinationIndexPath: NSIndexPath) -> NSIndexPath

    Objective-C

    - (NSIndexPath *)tableView:(UITableView *)tableView targetIndexPathForMoveFromRowAtIndexPath:(NSIndexPath *)sourceIndexPath toProposedIndexPath:(NSIndexPath *)proposedDestinationIndexPath

    Parameters

    tableView

    The table-view object that is requesting this information.

    sourceIndexPath

    An index-path object identifying the original location of a row (in its section) that is being dragged.

    proposedDestinationIndexPath

    An index-path object identifying the currently proposed destination of the row being dragged.

    Return Value

    An index-path object locating the desired row destination for the move operation. Return proposedDestinationIndexPath if that location is suitable.

    Discussion

    This method allows customization of the target row for a particular row as it is being moved up and down a table view. As the dragged row hovers over another row, the destination row slides downward to visually make room for the relocation; this is the location identified by proposedDestinationIndexPath.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Tells the delegate that the specified cell was removed from the table.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, didEndDisplayingCell cell: UITableViewCell, forRowAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)tableView:(UITableView *)tableView didEndDisplayingCell:(UITableViewCell *)cell forRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object that removed the view.

    cell

    The cell that was removed.

    indexPath

    The index path of the cell.

    Discussion

    Use this method to detect when a cell is removed from a table view, as opposed to monitoring the view itself to see when it appears or disappears.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the specified header view was removed from the table.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, didEndDisplayingHeaderView view: UIView, forSection section: Int)

    Objective-C

    - (void)tableView:(UITableView *)tableView didEndDisplayingHeaderView:(UIView *)view forSection:(NSInteger)section

    Parameters

    tableView

    The table-view object that removed the view.

    view

    The header view that was removed.

    section

    The index of the section that contained the header.

    Discussion

    Use this method to detect when a header view is removed from a table view, as opposed to monitoring the view itself to see when it appears or disappears.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the specified footer view was removed from the table.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, didEndDisplayingFooterView view: UIView, forSection section: Int)

    Objective-C

    - (void)tableView:(UITableView *)tableView didEndDisplayingFooterView:(UIView *)view forSection:(NSInteger)section

    Parameters

    tableView

    The table-view object that removed the view.

    view

    The footer view that was removed.

    section

    The index of the section that contained the footer.

    Discussion

    Use this method to detect when a footer view is removed from a table view, as opposed to monitoring the view itself to see when it appears or disappears.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Asks the delegate if the editing menu should be shown for a certain row.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, shouldShowMenuForRowAtIndexPath indexPath: NSIndexPath) -> Bool

    Objective-C

    - (BOOL)tableView:(UITableView *)tableView shouldShowMenuForRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object that is making this request.

    indexPath

    An index-path object locating the row in its section.

    Return Value

    YEStrue if the editing menu should be shown positioned near the row and pointing to it, otherwise NOfalse. The default value is NOfalse.

    Discussion

    If the user tap-holds a certain row in the table view, this method (if implemented) is invoked first. Return NOfalse if the editing menu shouldn’t be shown—for example, the cell corresponding to the row contains content that shouldn’t be copied or pasted over.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Asks the delegate if the editing menu should omit the Copy or Paste command for a given row.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, canPerformAction action: Selector, forRowAtIndexPath indexPath: NSIndexPath, withSender sender: AnyObject) -> Bool

    Objective-C

    - (BOOL)tableView:(UITableView *)tableView canPerformAction:(SEL)action forRowAtIndexPath:(NSIndexPath *)indexPath withSender:(id)sender

    Parameters

    tableView

    The table-view object that is making this request.

    action

    A selector type identifying the copy: or paste: method of the UIResponderStandardEditActions informal protocol.

    indexPath

    An index-path object locating the row in its section.

    sender

    The object that initially sent the copy: or paste: message. T

    Return Value

    YEStrue if the command corresponding to action should appear in the editing menu, otherwise NOfalse. The default value is NOfalse.

    Discussion

    This method is invoked after tableView:shouldShowMenuForRowAtIndexPath:. It gives the developer the opportunity to exclude one of the commands—Copy or Paste—from the editing menu. For example, the user might have copied some cell content from one row but wants to paste into another row that doesn’t take the copied content. In a case like this, return NOfalse from this method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Tells the delegate to perform a copy or paste operation on the content of a given row.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, performAction action: Selector, forRowAtIndexPath indexPath: NSIndexPath, withSender sender: AnyObject!)

    Objective-C

    - (void)tableView:(UITableView *)tableView performAction:(SEL)action forRowAtIndexPath:(NSIndexPath *)indexPath withSender:(id)sender

    Parameters

    tableView

    The table-view object that is making this request.

    action

    A selector type identifying the copy: or paste: method of the UIResponderStandardEditActions informal protocol.

    indexPath

    An index-path object locating the row in its section.

    sender

    The object that initially sent the copy: or paste: message.

    Discussion

    The table view invokes this method for a given action if the user taps Copy or Paste in the editing menu. The delegate can do whatever is appropriate for the action; for example, for a copy, it can extract the relevant cell content for the row at indexPath and write it to the general pasteboard or an application (private) pasteboard. See UIPasteboard Class Reference for further information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Asks the delegate if the specified row should be highlighted.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, shouldHighlightRowAtIndexPath indexPath: NSIndexPath) -> Bool

    Objective-C

    - (BOOL)tableView:(UITableView *)tableView shouldHighlightRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object that is making this request.

    indexPath

    The index path of the row being highlighted.

    Return Value

    YEStrue if the row should be highlighted or NOfalse if it should not.

    Discussion

    As touch events arrive, the table view highlights rows in anticipation of the user selecting them. As it processes those touch events, the table view calls this method to ask your delegate if a given cell should be highlighted. Your delegate can implement this method and use it to prevent the highlighting of a row when another row is already selected or when other relevant criteria occur.

    If you do not implement this method, the default return value is YEStrue.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the specified row was highlighted.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, didHighlightRowAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)tableView:(UITableView *)tableView didHighlightRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object that highlighted the cell.

    indexPath

    The index path of the row that was highlighted.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the highlight was removed from the row at the specified index path.

    Declaration

    Swift

    optional func tableView(_ tableView: UITableView, didUnhighlightRowAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)tableView:(UITableView *)tableView didUnhighlightRowAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    tableView

    The table-view object that removed the highlight from the cell.

    indexPath

    The index path of the row that had its highlight removed.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.