tvos-patterns

tvOS Platform Patterns

Siri Remote Input

tvOS uses the Siri Remote — all interaction is through focus and button presses:

// Handle directional movement
.onMoveCommand { direction in
    switch direction {
    case .up: moveUp()
    case .down: moveDown()
    case .left: moveLeft()
    case .right: moveRight()
    @unknown default: break
    }
}

// Handle Play/Pause button
.onPlayPauseCommand {
    togglePlayback()
}

// Handle Menu/Back button
.onExitCommand {
    dismiss()
}

// Long press on select button
.onLongPressGesture {
    showOptions()
}

Media Playback (AVKit)

import AVKit

struct PlayerView: View {
    let url: URL
    @State private var player: AVPlayer?

    var body: some View {
        VideoPlayer(player: player)
            .onAppear {
                player = AVPlayer(url: url)
                player?.play()
            }
            .onDisappear {
                player?.pause()
            }
            .ignoresSafeArea()
    }
}

Top Shelf Extension

The only supported extension type on tvOS — shows content on the home screen:

// In Targets/TopShelf/ContentProvider.swift
import TVServices

struct TopShelfProvider: TVTopShelfProvider {
    var topShelfStyle: TVTopShelfContentStyle { .sectioned }

    var topShelfItems: [TVTopShelfSectionedItem] {
        let section = TVTopShelfItemCollection(items: [
            makeItem(id: "1", title: "Featured Movie", imageURL: url1),
            makeItem(id: "2", title: "New Release", imageURL: url2),
        ])
        section.title = "Featured"
        return [section]
    }

    func makeItem(id: String, title: String, imageURL: URL) -> TVTopShelfSectionedItem {
        let item = TVTopShelfSectionedItem(identifier: id)
        item.title = title
        item.setImageURL(imageURL, for: .screenScale1x)
        item.displayAction = TVTopShelfAction(url: URL(string: "myapp://item/\(id)")!)
        return item
    }
}

Parallax Effect (Focus Art)

tvOS automatically applies parallax effects to images in focused buttons: