tvOS Design Guidelines

• Screen Sizes
• Safe Area
• App Icon
• Top Shelf
• Splash Screen
• Focus Engine
• Tab Bar and Navigation Hierarchies
• Search
• Text Input

• Video Player
• Alerts
• Loading
• Scrolling Text
• App Lifecycle
• In-App-Purchases
• App Versioning
• Other important notes & limitations of tvOS
• Additional features of tvOS

All tvOS apps can run in only two sizes:

• (@1x)-Mode: 1920×1080px (Full HD)
• (@2x)-Mode: 3840×2160px (4K)

Non-vector image assets should be provided in two sizes (@1x) and (@2x) for sharp rendering.

As usual point values for sizes, spacing, etc. are defined in the (@1x) / Full HD-Mode and then scaled up appropriately.

Example:

An element has a 200pt width. This translates to 200px in Full HD-Mode and 400px in 4K-Mode.

To accommodate possible overscan, tvOS apps should respect a safe area to ensure UI elements and content are always visible:

• Top, Bottom: 60pt
• Left, Right: 80pt

tvOS App Icons have special requirements because they are so-called layered images which offer a parallax effect on the home screen.

They consist of up to 5 layers and need to be provided in the following sizes:

• (@1x): 400×240px
• (@2x): 800×480px

Please refer to these pages for specific requirements and specifications:

• Layered images
• App Icons
• tvOS app icon sizes

When an app is placed in the first row of the tvOS home screen and focused, the user can see a large top shelf on the screen which can contain rich content previews for the app.

Fallback Image (required)

This rich UI is not required, but static fallback images must always be provided in the following sizes:

• (@1x): 2320×720px
• (@2x): 4640×1440px

Important: Make sure that relevant content is placed inside the middle 1920 pixels (or 3840px @2x) so it doesn't get cut off on the sides.

Rich Content

Read more about it here HIG – Top Shelf

Further reading:

HIG – Top Shelf

The splash screen is shown briefly when an app is launched and can only contain pre-defined static content — most commonly a full-screen image.

This launch image has to be provided in the following sizes:

• (@1x): 1920×1080px
• (@2x): 3840×2160px

Swiping

As with other smart TV platforms the user can move around the interface using a remote with distinct direction button presses (Up, Down, Left, Right).

But unlike other platforms, the main mode of interaction is swiping. The user can use swipe gestures on the remote to focus elements. This takes into account swipe duration and velocity to enable "skipping" elements quickly (e.g. scrolling through a long list of film covers).

This needs to be considered when designing certain UI elements that would otherwise rely on phrasing like "Press Up".

Focus Effects

Another important distinction on tvOS is the convention of adding a tilt effect on a focused element. In addition to any size, color or shape differences on a focused UI element, the element should also tilt when the user moves their finger on the remote slightly. To prevent overlapping, you need to provide enough spacing around elements.

Further reading:

• HIG – Remotes
• HIG – Focus and selection

Tab Bar

One of the most common structures for arranging different areas of an app is using tabs. tvOS provides a native tab bar interface you can use out-of-the-box.

As is convention on Apple platforms, each tab provides a separate navigation hierarchy which is usually not reset when switching to a different tab and going back again. The user can press the back button on the remote to pop to the previous screen inside of a hierarchy.

Screen Presentation and Modals

It's also very common to present screens on tvOS. On Apple platforms this means that a screen is shown (in full screen) on top of another screen. You can layer many screens on top of each other which in itself creates another hierarchy outside of the main tab interface.

This behavior is demonstrated in the GIF below. The detail screen for A Thin Line is presented full screen on top of the main tab bar interface. The detail screen for Episode 1 – Climate.Leaks is then presented on top of that. As with other navigation hierarchies, the user can press the back button to dismiss a presented screen.

On tvOS you are fairly limited when it comes to search. You need to use the Apple-provided native search interface (marked with red on the screenshot) which includes a full-width text input, keyboard and dictation feature. You can provide a placeholder text (e.g. Artists, Songs, Lyrics and More in the screenshot below). You cannot change the size or styling of this component.

Text fields

Similar to search, you are extremely limited in customizing text fields. You can only change the size and placeholder text. When the user clicks on a text field the native full-screen keyboard is opened. You can provide a hint to tvOS which kind of text should be entered (e.g. email, password) for the most useful keyboard to be shown.

PIN Input

For digit-only text, tvOS provides a special digit input screen with a title, prompt and fixed number of digits. We can present this screen on a button press (e.g. a "Set PIN" button).

We very strongly recommend using the native tvOS player interface for video playback. It covers all common use cases, provides a platform-consistent experience, and many useful affordances out-of-the-box.

Important notes and limitations

The native tvOS player heavily utilizes the metadata of the media asset to show the appropriate UI.

For example a live stream can show a Live badge and offers a slightly different scrubbing interface which shows actual times and offsets when scrubbing to the past.

Language and subtitle selection is also based on the media assets information. The same goes for frame previews during scrubbing (known as Trick Play).

More info on HLS authoring for Apple platforms: HLS Authoring Specification for Apple Devices

For HLS videos / streams subtitles must be included in the manifest to be available in the player interface.

Subtitle appearance and styling (e.g. size, color, background) are customized in the global tvOS settings to provide accessibility affordances. All apps should respect these settings. The native player UI automatically does this.

Basic Metadata

You can display a large title and a smaller subtitle. By default this is based on the media asset metadata.

The player UI has so called transport bar items which are represented by icons and can open dropdown menus on click.

You can add custom items with your own menus. Only the button icon and content of the menu is customizable. The styling is not customizable.

An item can also just act as a simple button or toggle without opening a dropdown menu (e.g. a Like button).

By default there are two menus based on the media asset: language selection and subtitle selection.

For more advanced use cases, the player offers content tabs. These are positioned below the transport bar and offer more customizability. By default there is an Info tab which displays various metadata based on the media asset and provides up to two customizable buttons on the right (e.g. From Beginning in the screenshot).

You can also create your own content tabs (e.g. Chapters and Up Next in the screenshot). These content tabs are always full-width and the height is determined by the tallest content tab.

Inside these tabs you have a lot more flexibility and can show a custom interface.

You can show a single button on the video in the bottom right corner. The most common use case would be a Skip Intro button at certain times. It can have an icon and a title. Styling is not customizable.

You can present native alerts to show important information to users and provide one or more actions.

You can use the standard activity indicator to indicate to the user when data is being loaded.

While it's possible to display long text in a scrolling view on tvOS there are some important considerations that need to be made.

Scrolling text works using the tracking input directly, which offers a similar experience to iOS. So if the user is moving their finger up, the text scrolls down.

This means that there shouldn't be any focusable elements above or below the scrollable text, because that would directly contradict any scrolling gestures.

Possible workarounds for this:

1. Place buttons to the side of the scrolling text

2. Present the scrolling text on a new screen above all other content. The user can then close it by pressing the back button on the remote.

Unlike most other smart TV platforms, tvOS supports app backgrounding. This means that an app is not actually quit when the user goes to the home screen, opens another app or puts the Apple TV to sleep.

Apps are only really quit when the operating system needs more resources or the user force-quits the app from the app switcher.

App Start

So there are actually 2 main ways to open / start / launch an app.

1. Cold Start

The app was actually quit before and was not in memory anymore. This happens e.g. after the Apple TV reboots, an app update, force-quit by the user or when tvOS needs more system resources for other things.

In this case we need to setup the whole app structure from scratch, load necessary resources, etc.

2. Warm Start / Hot Start

This case is much more common. The app was only suspended or backgrounded and is still in memory in its last-seen state.

There needs to be much more design considerations for this case, because this could happen seconds, hours, days or sometimes even weeks after the app was "closed".

Common questions that need to be asked in this case:

• When and how often should data be refreshed?
• After what interval should certain UI states be reset?

All Lifecycle States

• Not Running (not in memory, completely quit)
• Suspended (in memory, but cannot do any work)
• Background (can execute small tasks, app not visible)
• Inactive (shouldn't do heavy work, app visible but not interactive)
• Active (heavy work possible, app visible and fully interactive)

Disclaimer: This is not legal advice. Please consult the App Review Guidelines and legal advisors.

Basics

If you want to offer digital products or subscriptions in your app, you generally need to use Apple's In-App-Purchase (IAP) system and cannot use or link to your own payment systems.

Offerings must be configured in App Store Connect (the App Store backend) and can then be fetched in the app to display correct local pricing and any applicable discounts.

Products are purchased and linked to the user's Apple ID while Apple takes 15% or 30% of the revenue, depending on the circumstance.

App developers cannot explicitly offer refunds, the user must request a refund directly from Apple.

The app can only check if the current user has or has not purchased a particular item based on an App Store Receipt that is stored locally on device.

Linking to Your Account System

You can link this receipt info with your own user management system for any special needs (e.g. cross-platform access, analytics, customer support).

The app also needs to provide a way for the user to restore their purchases. Technically this means refreshing the receipt from the App Store. Sometimes the user needs to re-enter their Apple ID credentials, so this restoring should not be triggered automatically.

If you link purchases to your own account system, you need to decide how to handle a restored receipt (e.g. if the user is not logged in, if the user is logged in with a different account then the original account when the purchase was made, etc.).

We recommend RevenueCat if you don't want to implement this receipt validation and IAP management in your own backend and to vastly simplify the client implementation. It offers great SDKs and Web APIs to connect to your own backend.

Product Screen Design Guidelines

Apple has strict guidelines the app needs to adhere to when it comes to purchase screens. Please consult the Human Interface Guidelines and App Review Guidelines for further details:

• Human Interface Guidelines – IAP
• App Review Guidelines - IAP

On Apple platforms, apps have two values which represent a version.

1. (Marketing) Version

Apple Docs — CFBundleShortVersionString

This version is displayed to the user in the app store. It needs to be unique (and increased) for each published app build.

The required format is three period-separated integers, such as 10.14.1. The string can only contain numeric characters (0-9) and periods.

Examples

• 1.0
• 2.1.0
• 1.3.11
• 55.34
• 2023.4

Apple Docs — CFBundleVersion

2. Build Number

This number is used by the app store to determine if an app build is different / newer than another one. So this number has to be unique (and increased) for each uploaded app build.

The same format as (marketing) version is allowed, but generally only a single integer value is used.

You can upload multiple app builds with the same (marketing) version 2.0 for testing, but each of them has to have a different build number, e.g.: 2.0 (653), 2.0 (654), 2.0 (700).

Squircles

A small and fun one: Apple likes to use Squircles for many of their UI elements (e.g. app icons, buttons, etc.). So your app may use them too.

Offline mode

Unlike many other smart TV platforms, it's entirely possible to open an app while having no internet connection. So it's important to provide appropriate UI states and necessary information to the user in those circumstances.

No Quitting

It's not possible to programmatically close an app (without deliberately crashing it).

So there is no way to provide a UI like "Are you sure you want to quit the app? Yes / No".

The user closes the app by pressing / holding the back button or pressing the TV button on the remote.

Language Settings

We recommend using the configured system language to determine the app language and to not implement in-app language settings.

Limited Blur

To incorporate blur effects in an app, you should use one of the Apple-provided blur effects.

There is no straightforward way to set a blur-radius value you might know from CSS. But you can slightly tweak the standard effects by adjusting the alpha value.

Some experimentation might be necessary to get the desired result.

No Local Storage

In general tvOS doesn't allow for permanent local storage. Critical data needs to be stored on an external server or in iCloud.

Apps can cache data locally, but the system may purge the cache at any time when the app is not running.

The only exception to this are the so-called UserDefaults and the Keychain. These are simple key-value storage mechanisms for basic preferences and credentials, respectively. They have very limited capabilities and hard size limits and should therefore be used sparingly.

No Web Content

There is no web browser on tvOS and thus you generally cannot show web content.

However, in specific cases it can still be useful to manually fetch and parse simple HTML pages to render formatted texts. All valid tags and corresponding stylings must be defined and implemented beforehand.

Analytics

App Tracking Transparency

Before enabling any third-party analytics or tracking frameworks, apps must ask the user for permission.

See more: App Privacy

Kids Apps

It might be relevant to note that third-party analytics are forbidden in apps targeted in th Kids Category by Apple's app review guidelines.

Apple App Review Guidelines — Kids Category

Dark mode & light mode

tvOS supports system-wide dark mode and light mode. Apps can change their appearance appropriately.

Universal Search & TV app integration

Apple TV App and Universal Search Guide

Apple Video Partner Program