Help users discover your app. Add top shelf content and a description of your tvOS app to be displayed on a TV.


Apps on tvOS often have built-in media content, access media content stored on a remote server, or have other information to display to the user. For example, a weather app might access video files on a server showing the weather in different locals, and have other content items representing ongoing weather alerts. To help users discover this content when your app is not the foreground app, you can highlight your content in the Top Shelf area of the Apple TV main menu. For design guidance, see Top Shelf in tvOS Human Interface Guidelines.

You provide Top Shelf information by adding a Top Shelf app extension to your app. Your extension returns an array describing available content for your app, and the system uses this information to update the Top Shelf area. You describe your media to the operating system using TVContentItem objects. Each TVContentItem object represents either a piece of content or acts as a container for other TVContentItem objects. A content object typically includes an image and a title for tvOS to display, along with other metadata related to the content item.

In order for tvOS to track content items, you create a unique string for each content item. You can choose your own algorithm to create these identifiers. However, any string you create should identify its content item forever; identifiers should never be reused to identify new content. You package an identifier in a TVContentIdentifier object, which include the string and the parent container the content item is contained in.

To summarize, to provide descriptions of content to Apple TV, you must:

  • Organize your media and app content, either as a single list or in a hierarchical model

  • Design an algorithm or standard that supplies each content item with a unique content identifier string

  • Create a TVContentItem object for each container or content item

  • Add an app extension whose main class implements the TVTopShelfProvider protocol


Top Shelf Extensions

protocol TVTopShelfProvider

The TVTopShelfProvider protocol is implemented by apps to provide items for display in the main menu’s Top Shelf user interface on an Apple TV.

class TVContentIdentifier

A TVContentIdentifier object uniquely identifies media content in either a single piece or a collection.

class TVContentItem

A TVContentItem object describes either a piece of content or a container for other content items. The exact details of what a content item is are dependent on your app. For example, a content item might be a piece of media or it might provide access to news or other content available to your app.

func TVTopShelfImageSize(shape: TVContentItemImageShape, style: TVTopShelfContentStyle) -> CGSize

Returns the ideal size for an image, according to its particular shape and style.