<!--
{
  "availability" : [
    "iOS: 12.0.0 -",
    "iPadOS: 12.0.0 -",
    "macCatalyst: 13.1.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CarPlay",
  "identifier" : "/documentation/CarPlay/CPListItem",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "CarPlay"
    ],
    "preciseIdentifier" : "c:objc(cs)CPListItem"
  },
  "title" : "CPListItem"
}
-->

# CPListItem

A selectable row in a list template.

```
@MainActor class CPListItem
```

## Overview

A list item manages the content of a single row in a list template. CarPlay manages the layout of a list item and may adjust its layout to allow for the display of auxiliary content, such as an accessory or a Now Playing indicator. A list item can display primary and secondary text and an image. It can also show an accessory or custom accessory image, and one of several indicators that the system provides.

You assign a [`handler`](/documentation/CarPlay/CPListItem/handler) to a list item that CarPlay executes when the user selects the item. The handler receives the item and a closure that you must call after you finish processing the selection.

CarPlay doesn’t support custom list item types. Instead, use the [`userInfo`](/documentation/CarPlay/CPListItem/userInfo) property to attach a value to the list item that provides additional context, such as specifying  a model object that corresponds to the item.

## Topics

### Creating a List Item

[`-  initWithText:detailText:`](/documentation/CarPlay/CPListItem/init(text:detailText:))

Creates a list item with primary and secondary text.

[`-  initWithText:detailText:image:`](/documentation/CarPlay/CPListItem/init(text:detailText:image:))

Creates a list item with primary text, secondary text, and an image.

[`-  initWithText:detailText:image:accessoryImage:accessoryType:`](/documentation/CarPlay/CPListItem/init(text:detailText:image:accessoryImage:accessoryType:))

Creates a list item that displays an accessory beside its content.

### Managing Configuration

[`enabled`](/documentation/CarPlay/CPListItem/isEnabled)

A Boolean value that indicates if the item is enabled.

[`handler`](/documentation/CarPlay/CPListItem/handler)

An optional closure that CarPlay invokes when the user selects the list item.

[`userInfo`](/documentation/CarPlay/CPListItem/userInfo)

An opaque value for the list item.

### Managing Accessories

[`accessoryType`](/documentation/CarPlay/CPListItem/accessoryType)

The accessory that the list item displays in its trailing region.

[`CPListItemAccessoryType`](/documentation/CarPlay/CPListItemAccessoryType)

The accessory types that a list item can display.

[`accessoryImage`](/documentation/CarPlay/CPListItem/accessoryImage)

The image that the list item displays in its trailing region.

[`-  setAccessoryImage:`](/documentation/CarPlay/CPListItem/setAccessoryImage(_:))

Updates the list item’s accessory image.

### Managing Content

[`text`](/documentation/CarPlay/CPListItem/text)

The list item’s primary text.

[`-  setText:`](/documentation/CarPlay/CPListItem/setText(_:))

Updates the list item’s primary text.

[`detailText`](/documentation/CarPlay/CPListItem/detailText)

The list item’s secondary text.

[`-  setDetailText:`](/documentation/CarPlay/CPListItem/setDetailText(_:))

Updates the list item’s secondary text.

[`image`](/documentation/CarPlay/CPListItem/image)

The image that the list item displays in its leading region.

[`-  setImage:`](/documentation/CarPlay/CPListItem/setImage(_:))

Updates the list item’s image.

[`maximumImageSize`](/documentation/CarPlay/CPListItem/maximumImageSize)

The maximum size of a list item’s image and accessory image.

### Managing Playback Information

[`explicitContent`](/documentation/CarPlay/CPListItem/isExplicitContent)

A Boolean value that determines whether the list item displays its explicit content indicator.

[`playing`](/documentation/CarPlay/CPListItem/isPlaying)

A Boolean value that determines whether the list item displays its Now Playing indicator.

[`playingIndicatorLocation`](/documentation/CarPlay/CPListItem/playingIndicatorLocation)

The location where the list item displays its Now Playing indicator.

[`CPListItemPlayingIndicatorLocation`](/documentation/CarPlay/CPListItemPlayingIndicatorLocation)

The locations where a list item can display the Now Playing indicator.

[`playbackProgress`](/documentation/CarPlay/CPListItem/playbackProgress)

The playback progress status for the content that the list item represents.

### Managing the Assistant Cell

[`AssistantCellPosition`](/documentation/CarPlay/CPListItem/AssistantCellPosition)

Constants to specify the position of the assistant cell.

[`AssistantCellVisibility`](/documentation/CarPlay/CPListItem/AssistantCellVisibility)

Constants to specify the visibility of the assistant cell.

### Deprecated

[Deprecated Symbols](/documentation/CarPlay/cplistitem-deprecated-symbols)

Review unsupported symbols and their replacements.

## Relationships

### Conforms To

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`CPListTemplateItem`](/documentation/CarPlay/CPListTemplateItem)

[`Sendable`](/documentation/Swift/Sendable)

[`Hashable`](/documentation/Swift/Hashable)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Escapable`](/documentation/Swift/Escapable)

[`CPPlayableItem`](/documentation/CarPlay/CPPlayableItem)

[`Copyable`](/documentation/Swift/Copyable)

[`Equatable`](/documentation/Swift/Equatable)

[`CPSelectableListItem`](/documentation/CarPlay/CPSelectableListItem)

[`CVarArg`](/documentation/Swift/CVarArg)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)