Class

UITableViewCell

The visual representation of a single row in a table view.

Declaration

@interface UITableViewCell : UIView

Overview

A UITableViewCell object is a specialized type of view that manages the content of a single table row. You use cells primarily to organize and present your app’s custom content, but UITableViewCell provides some specific customizations to support table-related behaviors, including:

  • Applying a selection or highlight color to the cell.

  • Adding standard accessory views, such as a detail or disclosure control.

  • Putting the cell into an editable state.

  • Indenting the cell's content to create a visual hierarchy in your table.

Your app’s content occupies most of the cell’s bounds, but the cell may adjust that space to make room for other content. Cells display accessory views on the trailing edge of their content area. When you put your table into edit mode, the cell adds a delete control to the leading edge of its content area, and optionally swaps out an accessory view for a reorder control.

Illustration showing the area of a cell by itself and with an accessory view and edit control. The content area of a cell shrinks as needed to accommodate the accessory view or edit controls.

Every table view must have at least one type of cell for displaying content, and tables may have multiple cell types to display different types of content. Your table’s data source object handles the creation and configuration of cells immediately before they appear onscreen. For information about how to create your table’s cells, see Filling a Table with Data.

Configuring Your Cell's Content

Configure the content and layout of your cells in your storyboard file. Tables have one cell type by default, but you can add more by changing the value in the table’s Prototype Cells attribute. In addition to configuring the cell’s content, make sure you configure the following attributes:

  • Identifier. Use this identifier (also known as a reuse identifier) to create the cell.

  • Style. Choose one of the standard types or define a custom cell.

  • Class. Specify a UITableViewCell subclass with your custom behavior.

For the standard types, UITableViewCell provides the views for displaying your content. All you have to do is assign values to the textLabel, detailTextLabel, and imageView properties of your cell. The following illustration shows how the values you supply are positioned within the cell’s content area. If you do not supply an image for your cell, the cell distributes the extra space to the other content views.

The standard layouts for table view cells

For information about how to customize the appearance of your cells, see Configuring the Cells for Your Table.

Topics

Creating a Table View Cell

- initWithStyle:reuseIdentifier:

Initializes a table cell with a style and a reuse identifier and returns it to the caller.

UITableViewCellStyle

An enumeration for the various styles of cells.

Reusing Cells

reuseIdentifier

A string used to identify a cell that is reusable.

- prepareForReuse

Prepares a reusable cell for reuse by the table view'€™s delegate.

Specifying Content for Standard Cell Styles

textLabel

The label used for the main textual content of the table cell.

detailTextLabel

The secondary label of the table cell if one exists.

imageView

The image view of the table cell.

Accessing Views of the Cell Object

contentView

The content view of the cell object.

backgroundView

The view used as the background of the cell.

selectedBackgroundView

The view used as the background of the cell when it is selected.

multipleSelectionBackgroundView

The background view to use for a selected cell when the table view allows multiple row selections.

Managing Accessory Views

accessoryType

The type of standard accessory view the cell should use (normal state).

accessoryView

A view that is used, typically as a control, on the right side of the cell (normal state).

editingAccessoryType

The type of standard accessory view the cell should use in the table view’s editing state.

editingAccessoryView

A view that is used typically as a control on the right side of the cell when it is in editing mode.

UITableViewCellAccessoryType

The type of standard accessory control used by a cell.

Managing Cell Selection and Highlighting

selectionStyle

The style of selection for a cell.

UITableViewCellSelectionStyle

The style of selected cells.

selected

A Boolean value that indicates whether the cell is selected.

- setSelected:animated:

Sets the selected state of the cell, optionally animating the transition between states.

highlighted

A Boolean value that indicates whether the cell is highlighted.

- setHighlighted:animated:

Sets the highlighted state of the cell, optionally animating the transition between states.

Editing the Cell

editing

A Boolean value that indicates whether the cell is in an editable state.

- setEditing:animated:

Toggles the receiver into and out of editing mode.

editingStyle

The editing style of the cell.

UITableViewCellEditingStyle

The editing control used by a cell.

showingDeleteConfirmation

A Boolean value that indicates whether the cell is currently showing the delete-confirmation button.

showsReorderControl

A Boolean value that determines whether the cell shows the reordering control.

Dragging the Row

userInteractionEnabledWhileDragging

A Boolean value indicating whether users can interact with a cell while it is being dragged.

- dragStateDidChange:

Notifies the cell that its drag status changed.

UITableViewCellDragState

Constants indicating the current state of a row involved in a drag operation.

Adjusting to State Transitions

- willTransitionToState:

Called to notify the cell that it is about to transition to a new cell state.

- didTransitionToState:

Called to notify the cell that it transitioned to a new cell state.

UITableViewCellStateMask

Constants used to determine the new state of a cell as it transitions between states.

Managing Content Indentation

indentationLevel

The indentation level of the cell’s content.

indentationWidth

The width for each level of indentation of a cell'€™s content.

shouldIndentWhileEditing

A Boolean value that controls whether the cell background is indented when the table view is in editing mode.

separatorInset

The inset values for the separator line drawn beneath the cell.

Managing Focus

focusStyle

The appearance of the cell when focused.

UITableViewCellFocusStyle

The style of focused cells.

Deprecated Methods

- initWithFrame:reuseIdentifier:

Initializes and returns a table cell object.

Deprecated
text

The text of the cell.

Deprecated
font

The font of the title.

Deprecated
textAlignment

A constant that specifies the alignment of text in the cell.

Deprecated
textColor

The color of the title text.

Deprecated
selectedTextColor

The color of the title text when the cell is selected.

Deprecated
lineBreakMode

The mode for wrapping and truncating text in the cell.

Deprecated
image

The image to use as content for the cell.

Deprecated
selectedImage

The image to use a cell content when the cell is selected.

Deprecated
hidesAccessoryWhenEditing

A Boolean value that determines whether the accessory view is hidden when the cell is being edited.

Deprecated
target

The target object to receive action messages.

Deprecated
editAction

The selector defining the action message to invoke when users tap the insert or delete button.

Deprecated
accessoryAction

The selector defining the action message to invoke when users tap the accessory view.

Deprecated

Relationships

Inherits From

See Also

Cells, Headers, and Footers

Configuring the Cells for Your Table

Specify the appearance and content of your table’s rows by defining one or more prototype cells in your storyboard.

Creating Self-Sizing Table View Cells

Create table view cells that support Dynamic Type and use system spacing constraints to adjust the spacing surrounding text labels.

Adding Headers and Footers to Table Sections

Differentiate groups of rows visually by adding header and footer views to your table view’s sections.

UITableViewHeaderFooterView

A reusable view that you place at the top or bottom of a table section to display additional information for that section.