Class

UITableViewCell

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

Declaration

class 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

init(style: UITableViewCell.CellStyle, reuseIdentifier: String?)

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

enum UITableViewCell.CellStyle

An enumeration for the various styles of cells.

Reusing Cells

var reuseIdentifier: String?

A string used to identify a cell that is reusable.

func prepareForReuse()

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

Specifying Content for Standard Cell Styles

var textLabel: UILabel?

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

var detailTextLabel: UILabel?

The secondary label of the table cell if one exists.

var imageView: UIImageView?

The image view of the table cell.

Accessing Views of the Cell Object

var contentView: UIView

The content view of the cell object.

var backgroundView: UIView?

The view used as the background of the cell.

var selectedBackgroundView: UIView?

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

var multipleSelectionBackgroundView: UIView?

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

Managing Accessory Views

var accessoryType: UITableViewCell.AccessoryType

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

var accessoryView: UIView?

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

var editingAccessoryType: UITableViewCell.AccessoryType

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

var editingAccessoryView: UIView?

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

enum UITableViewCell.AccessoryType

The type of standard accessory control used by a cell.

Managing Cell Selection and Highlighting

var selectionStyle: UITableViewCell.SelectionStyle

The style of selection for a cell.

enum UITableViewCell.SelectionStyle

The style of selected cells.

var isSelected: Bool

A Boolean value that indicates whether the cell is selected.

func setSelected(Bool, animated: Bool)

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

var isHighlighted: Bool

A Boolean value that indicates whether the cell is highlighted.

func setHighlighted(Bool, animated: Bool)

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

Editing the Cell

var isEditing: Bool

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

func setEditing(Bool, animated: Bool)

Toggles the receiver into and out of editing mode.

enum UITableViewCell.EditingStyle

The editing control used by a cell.

var showingDeleteConfirmation: Bool

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

var showsReorderControl: Bool

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

Dragging the Row

var userInteractionEnabledWhileDragging: Bool

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

func dragStateDidChange(UITableViewCell.DragState)

Notifies the cell that its drag status changed.

enum UITableViewCell.DragState

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

Adjusting to State Transitions

func willTransition(to: UITableViewCell.StateMask)

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

func didTransition(to: UITableViewCell.StateMask)

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

struct UITableViewCell.StateMask

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

Managing Content Indentation

var indentationLevel: Int

The indentation level of the cell’s content.

var indentationWidth: CGFloat

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

var shouldIndentWhileEditing: Bool

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

var separatorInset: UIEdgeInsets

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

Managing Focus

var focusStyle: UITableViewCell.FocusStyle

The appearance of the cell when focused.

enum UITableViewCell.FocusStyle

The style of focused cells.

Enumerations

enum UITableViewCell.SeparatorStyle

The style for cells used as separators.

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.

class UITableViewHeaderFooterView

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

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software