<!--
{
  "availability" : [
    "tvOS: 13.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "TVServices",
  "identifier" : "/documentation/TVServices/TVTopShelfCarouselItem",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "TV Services"
    ],
    "preciseIdentifier" : "c:objc(cs)TVTopShelfCarouselItem"
  },
  "title" : "TVTopShelfCarouselItem"
}
-->

# TVTopShelfCarouselItem

An item containing images, video, and other information that you want to display using a carousel-based interface.

```
class TVTopShelfCarouselItem
```

## Overview

A [`TVTopShelfCarouselItem`](/documentation/TVServices/TVTopShelfCarouselItem) object offers a more dynamic way to present your content than section-based items. When a carousel item first appears, it displays either a static image or a short looping video as its background. When the navigation focus stops on the item, the system plays the video in the item’s [`previewVideoURL`](/documentation/TVServices/TVTopShelfCarouselItem/previewVideoURL) property.

Create one or more [`TVTopShelfCarouselItem`](/documentation/TVServices/TVTopShelfCarouselItem) objects and fill them with information about your content. The system determines which properties of the object to display based on the content style. For the [`TVTopShelfCarouselContent.Style.details`](/documentation/TVServices/TVTopShelfCarouselContent/Style-swift.enum/details) style, the system displays all of the information in your carousel item. For the [`TVTopShelfCarouselContent.Style.actions`](/documentation/TVServices/TVTopShelfCarouselContent/Style-swift.enum/actions) style, the system focuses on the actions associated with your item. To specify the actions for both styles, use the inherited [`playAction`](/documentation/TVServices/TVTopShelfItem/playAction) and [`displayAction`](/documentation/TVServices/TVTopShelfItem/displayAction) properties of the object.

## Topics

### Specifying the Item Details

[`var contextTitle: String?`](/documentation/TVServices/TVTopShelfCarouselItem/contextTitle)

A localized string describing why the item is shown in the top shelf.

[`var summary: String?`](/documentation/TVServices/TVTopShelfCarouselItem/summary)

A descriptive summary of a movie or show.

[`var genre: String?`](/documentation/TVServices/TVTopShelfCarouselItem/genre)

The genre assigned to the movie or show.

[`var duration: TimeInterval`](/documentation/TVServices/TVTopShelfCarouselItem/duration)

The length of the movie or show, in seconds.

[`var creationDate: Date?`](/documentation/TVServices/TVTopShelfCarouselItem/creationDate)

The original release date of the content.

### Specifying the Content Previews

[`var cinemagraphURL: URL?`](/documentation/TVServices/TVTopShelfCarouselItem/cinemagraphURL)

The URL of a looping video to play, without sound, while the preview loads.

[`var previewVideoURL: URL?`](/documentation/TVServices/TVTopShelfCarouselItem/previewVideoURL)

The URL for the content’s trailer or preview.

### Adding Media Badges

[`var mediaOptions: TVTopShelfCarouselItem.MediaOptions`](/documentation/TVServices/TVTopShelfCarouselItem/mediaOptions-swift.property)

Information about the media format and presentation options.

[`struct MediaOptions`](/documentation/TVServices/TVTopShelfCarouselItem/MediaOptions-swift.struct)

Constants indicating the item’s audio and video capabilities.

### Adding Custom Attributes

[`var namedAttributes: [TVTopShelfNamedAttribute]`](/documentation/TVServices/TVTopShelfCarouselItem/namedAttributes)

Additional information to display for your content, such as a list of leading actors.

[`class TVTopShelfNamedAttribute`](/documentation/TVServices/TVTopShelfNamedAttribute)

An object you use to display additional information.

## Relationships

### Conforms To

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

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

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

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

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

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

### Inherits From

[`TVTopShelfItem`](/documentation/TVServices/TVTopShelfItem)

---

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)