Top Shelf Content

People use top shelf to discover new content, so it's a great opportunity to showcase lively, engaging content that encourages people to dive into your app for more. Apple defines several layout templates you can use to give people a compelling top shelf experience when they select your app in the Dock.

Best Practices

Help people jump right into playback. Top shelf provides a path to content that people care about most. The carousel layout templates both include two buttons by default: A primary button that should always begin playback and a More Info button that should open your app to a view that displays details about the content. For guidance, see Carousel Actions and Carousel Details.

Feature new content. For example, if you offer movies, showcase new releases; don't promote movies that people have already purchased, rented, or watched. Similarly, if you offer episodic content, feature episode or season trailers, new shows, new seasons, and shows that are coming soon, and avoid promoting content people have already watched or purchased.

Personalize favorite content. People are familiar with apps they put in the top shelf of the Apple TV Home screen and use them often. You can personalize the experience by showing targeted recommendations in the top shelf, allowing people to resume media playback or jump back into active gameplay.

Don’t show advertisements or prices. When people put your app at the top of the Home screen, you’ve already sold them on it. Don’t bombard them with ads that push them away and encourage your app to get demoted. Showing purchasable content in the top shelf is fine, but focus on new and exciting content, and never display prices.

Showcase compelling dynamic content. The videos and imagery you show in the top shelf should draw people in and make them crave more. Although your app can stick with the required static image, prefer implementing more captivating, dynamic top shelf content that focuses on the newest or highest rated content. (To learn how to create multilayer images, see Layered Images.)

Dynamic Content Layouts

Dynamic top shelf imagery can appear in several ways:

  • A carousel of fullscreen video and imagery that includes two buttons and optional details
  • A row of focusable content
  • A set of scrolling banners

Regardless of the layout style you use, show content that people care about the most and help them get to it quickly.

For downloadable top shelf image templates that can help you position your content, see Resources.

The carousel actions layout style focuses on fullscreen video and imagery and includes a few unobtrusive controls that help people see more. This layout style works especially well to showcase content that people already know something about. For example, it's great for displaying user-generated content—like photos—or new content from a franchise or show that people are likely to enjoy.

Screenshot of a featured movie with the play button selected.

Watch Spider-Man: Into the Spider-Verse Spider-Man: Into the Spider-Verse is available on the Apple TV app. Spider-Man: Into the Spider-Verse © 2018 Sony Pictures Animation Inc. All rights reserved. MARVEL and all related character names © & ™ 2019 MARVEL.

Provide a title. Include a succinct title, like the title of the show or movie or the title of a photo album. If necessary, you can also provide a brief subtitle. For example, a subtitle for a photo album could be a range of dates; a subtitle for an episode could be the name of the show.

This layout style extends the carousel actions layout style by giving you the opportunity to include some information about the content. For example, you might provide information like a plot summary, cast list, and other metadata that helps people decide whether to choose the content.

Screenshot of a featured movie, including metadata about the movie. The play button is selected.

Provide a title that identifies the currently playing content. The content title appears near the top of the screen so it's easy for people to read it at a glance. Above the title, you can also provide a succinct phrase or app attribution, like "Featured on My App".

Sectioned Content Row

This layout style shows a single labeled row of sectioned content. It’s commonly used to highlight recently viewed content, new content, or favorites. Content in the row is focusable, which lets people scroll through it as fast as they want. A label appears when an individual piece of content comes into focus, and small movements on the remote’s touch surface bring the focused image to life. A sectioned content row can be configured to show multiple labels, if desired.

Sectioned Content Row layout on the Apple TV Main Menu

Provide enough content to constitute a complete row. At a minimum, load enough images in a sectioned content row to span the full width of the screen. In addition, include at least one label for greater platform consistency and to provide additional context.

You can supply images of varying aspect ratios for a sectioned content row. The following sizes are supported:

Poster (2:3)

Content Layout 2x3 Grid

Aspect Image size (@1x) Image size (@2x)
Actual size 404px × 608px (404pt × 608pt @1x) 808px × 1216px (404pt × 608pt @2x)
Focused/Safe zone size 380px × 570px (380pt × 570pt @1x) 760px × 1140px (380pt × 570pt @2x)
Unfocused size 333px × 570px (333pt × 570pt @1x) 666px × 1140px (333pt × 570pt @2x)
Square (1:1)

Content Layout 1x1 Grid

Aspect Image size (@1x) Image size (@2x)
Actual size 608px × 608px (608pt × 608pt @1x) 1216px × 1216px (608pt × 608pt @2x)
Focused/Safe zone size 570px × 570px (570pt × 570pt @1x) 1140px × 1140px (570pt × 570pt @2x)
Unfocused size 500px × 500px (500pt × 500pt @1x) 1000px × 1000px (500pt × 500pt @2x)
HDTV (16:9)

Content Layout 16x9 Grid

Aspect Image size (@1x) Image size (@2x)
Actual size 908px × 512px (908pt × 512pt @1x) 1816px × 1024px (908pt × 512pt @2x)
Focused/Safe zone size 852px × 479px (852pt × 479pt @1x) 1704px × 958px (852pt × 479pt @2x)
Unfocused size 782px × 440px (782pt × 440pt @1x) 1564px × 880px (782pt × 440pt @2x)

Be aware of additional scaling when combining image sizes. If your top shelf design includes a mixture of image sizes, keep in mind that images will automatically scale up to match the height of the tallest image if necessary. For example, an HDTV image scales to 500 pixels high if included in a row with a poster or square image.

Scrolling Inset Banner

This layout shows a series of large images, each of which spans almost the entire width of the screen. Apple TV automatically scrolls through these banners from left to right on a preset timer until one is brought into focus. The sequence circles back to the beginning once the final image is reached.

When a banner is in focus, a small, circular gesture on the remote’s touch surface enacts the system focus effect, animating the item, applying lighting effects, and, if the banner contains multiple layers, producing a 3D effect. Swiping on the touch surface pans to the next or previous banner in the sequence. Use this style to showcase rich, captivating content, such as a popular new movie.

Example of a Scrolling Inset Banner layout

Provide three to eight images. A minimum of three images is recommended for a scrolling banner to feel effective. More than eight images makes it harder to manually navigate to a specific image.

If you need text, add it to your image. This layout style doesn’t show labels under content, so any text must be part of the image itself. In layered images, consider elevating text by placing it on a dedicated layer above the others. Add the text to the accessibility label of the image too, so VoiceOver can read it to the visually impaired. For guidance, see Accessibility. To learn about VoiceOver, see tvOS Accessibility and UIKit Accessibility.

The following size is supported for a scrolling inset banner image:

Extra Wide

Content Layout Extra Wide Grid

Aspect Image size (@1x) Image size (@2x)
Actual size 1940px × 692px (1940pt × 692pt @1x) 3880px × 1384px (1940pt × 692pt @2x)
Focused/Safe zone size 1740px × 620px (1740pt × 620pt @1x) 3480px × 1240px (1740pt × 620pt @2x)
Unfocused size 1740px × 560px (1740pt × 560pt @1x) 3480px × 1120px (1740pt × 560pt @2x)

Static Image

If you don't support fullscreen top shelf content, you need to supply a minimum of one static image that can be displayed when your app is in the Dock and in focus.

Image size (@1x) Image size (@2x)
2320px × 720px (2320pt × 720pt @1x) 4640px × 1440px (2320pt × 720pt @2x)

Provide a visually rich static image. Your app’s static top shelf image is used when dynamic content isn’t provided or is unavailable. Use it as an opportunity to highlight your brand.

Don’t imply interactivity in a static image. The static top shelf image isn’t focusable, so it shouldn't include elements that make it appear interactive.