tvOS Focus Engine: SwiftUI Patterns for the Siri Remote

Apple TV is the only Apple platform without a touch surface. The user navigates by directional swipes and button presses on the Siri Remote, and every interaction goes through the focus engine: a system that decides which element receives focus next based on geometry, hierarchy, and the developer’s declared focus structure¹. SwiftUI on tvOS exposes a focused (forgive the pun) vocabulary for working with the engine: .focusable, @FocusState, .focused, .focusSection, .prefersDefaultFocus, and .focusEffectDisabled. Apps that adopt the vocabulary feel native; apps that fight it produce the experience of a remote that refuses to navigate where the user expects.

The post walks the focus engine API surface with the patterns that ship. The frame is “what the engine assumes and how SwiftUI lets you cooperate,” because focus design that works on iOS through tap-and-scroll often fails on tvOS, and the cluster’s Apple Platform Matrix post argued that tvOS earns its slot only with focus-aware UI.

TL;DR

• The focus engine resolves focus by geometry: it picks the closest focusable view in the swipe direction¹. Apps cooperate by declaring focusable views, focus sections, and default-focus targets.
• @FocusState (with .focused(_:equals:)) is the SwiftUI primitive for programmatic focus control. The same property wrapper works on iOS, macOS, watchOS, and tvOS, but tvOS is where it earns its keep².
• .focusSection() groups multiple focusable views into a single focus target for between-section navigation, then lets the engine pick within the section³. Use it for button rows, card grids, sidebar sections.
• .prefersDefaultFocus(_:in:) declares which view receives focus when the user enters a context (a screen, a popover, a tab). Pair with @Namespace to scope the default⁴.
• The system focus effect (the highlight that grows around the focused view) is automatic. Disable it with .focusEffectDisabled() only when implementing a custom focus visual; otherwise the platform-native effect is the right one.

How The Focus Engine Decides

The focus engine processes swipe input from the Siri Remote and resolves “where does focus go next?” through a hierarchical search¹:

1. Read the swipe direction (up, down, left, right).
2. Within the current focus context, find focusable views whose frames are in that direction relative to the currently-focused view.
3. Pick the geometrically-closest one along the swipe axis (with a small bias toward staying aligned with the current view’s center).
4. If no focusable view is in that direction, the swipe is consumed without moving focus.

The implication: the visual layout of focusable views matters as much as their logical hierarchy. Two buttons offset diagonally produce ambiguous navigation; two buttons aligned vertically produce predictable up/down. The HIG-recommended pattern for grids and lists is alignment first, decoration second.

Apps participate in the engine through SwiftUI’s focus modifiers. The default behavior is that views with explicit interactive intent (Button, NavigationLink, TextField) are focusable; static views (Text, Image, container views like VStack) are not.

Making Custom Views Focusable

The .focusable() modifier marks a view as a focus target⁵. The optional Boolean parameter conditions the focusability:

struct PosterCard: View {
    let movie: Movie
    @FocusState private var isFocused: Bool

    var body: some View {
        VStack {
            Image(movie.posterName)
                .resizable()
                .aspectRatio(2/3, contentMode: .fit)
            Text(movie.title)
                .font(.headline)
        }
        .focusable(true)
        .focused($isFocused)
        .scaleEffect(isFocused ? 1.1 : 1.0)
        .animation(.spring(), value: isFocused)
    }
}

The view becomes a focus target the engine can land on. The pattern is right for clickable cards, custom buttons, and any composite view that should accept the user’s attention. Without .focusable(), the cluster of Image + Text would be skipped by the engine.

@FocusState and .focused(_:equals:) for Programmatic Control

When the app needs to direct focus (after a navigation transition, after a search submit, after dismissing a modal), @FocusState is the SwiftUI primitive²:

struct LoginView: View {
    enum Field { case username, password, submit }
    @FocusState private var focusedField: Field?
    @State private var username = ""
    @State private var password = ""

    var body: some View {
        VStack {
            TextField("Username", text: $username)
                .focused($focusedField, equals: .username)

            SecureField("Password", text: $password)
                .focused($focusedField, equals: .password)

            Button("Sign In") { /* ... */ }
                .focused($focusedField, equals: .submit)
        }
        .onAppear {
            focusedField = .username
        }
    }
}

The @FocusState enum value tracks which field is focused; assigning a new value programmatically moves focus to the corresponding view. The Hashable enum case is the convention; multiple fields with the same case value would be ambiguous.

For a single focusable view, @FocusState var isFocused: Bool plus .focused($isFocused) is the simpler form. The Boolean variant is right when the question is “is this view focused?”; the enum variant is right for “which view in this set?”.

.focusSection() For Grouping

Without .focusSection(), every focusable view participates in the engine’s geometric search at the same level. With it, a container becomes a focus group: navigation to/from the section is one decision, navigation within the section is another³. Note that .focusSection() is tvOS- and macOS-only; it has no effect on iOS, iPadOS, watchOS, or visionOS.

HStack {
    VStack {
        Button("Settings") { ... }
        Button("Profile") { ... }
        Button("Logout") { ... }
    }
    .focusSection()

    VStack {
        ContentList(items: items)
    }
    .focusSection()
}

The two VStacks become navigable as units. The user swipes right from the sidebar to land in the content area; once there, the engine handles within-area navigation. Without .focusSection(), swipes from a sidebar button might land on an arbitrary content item that happens to be geometrically closest, producing UX that feels random.

The right pattern: every UI region with internal focus structure (sidebars, card grids, tab bars, pagination controls) gets a .focusSection() modifier on its container. The engine then navigates between sections at the macro level and within sections at the micro level.

.prefersDefaultFocus(_:in:) For Initial Focus

When a screen appears or a popover opens, something needs initial focus. Without explicit guidance, the engine picks the first focusable view in the layout, which is often wrong (the back button instead of the primary action, an obscure list cell instead of the play button)⁴.

struct MovieDetailView: View {
    let movie: Movie
    @Namespace private var detailNamespace

    var body: some View {
        VStack {
            HStack {
                Button("Back") { ... }
                Spacer()
            }

            PosterImage(movie: movie)

            Button("Play") { ... }
                .prefersDefaultFocus(in: detailNamespace)

            Button("Add to Watchlist") { ... }
        }
        .focusScope(detailNamespace)
    }
}

The @Namespace plus .focusScope() defines the focus boundary, and .prefersDefaultFocus(in:) declares the preferred initial focus within that scope. When the screen appears, focus lands on Play.

The pattern is the right one for any view that the user enters with an obvious “what to do first” expectation: Play on a movie detail page, Sign In on a login screen, Get Started on an onboarding screen.

Custom Focus Effects (And When To Disable The Default)

The system focus effect is the soft-edged glow that grows around a focused view. It scales the view slightly, adds a subtle shadow, and animates with the platform’s standard timing. For most apps, the default is correct; it matches every other tvOS app and lets users learn the platform’s vocabulary.

For apps that need a custom focus visual (a brand-specific glow, a content-aware effect, a focus ring that conflicts with the default), .focusEffectDisabled() opts out of the system treatment⁶:

Button {
    play(movie)
} label: {
    PosterImage(movie: movie)
        .overlay(focusBorder)
        .scaleEffect(isFocused ? 1.05 : 1.0)
}
.focusEffectDisabled()
.focused($isFocused)

The custom view is responsible for indicating focus visually; the system no longer interferes. The trade-off: every focus visual must be designed and implemented by the app rather than inherited. For most apps, the system effect is the right choice.

Common tvOS Focus Failures

Three patterns that produce poor tvOS UX:

Buttons that don’t accept focus. A custom button rendered as HStack { Image; Text } without .focusable() is invisible to the engine. The Siri Remote’s swipes skip it. Fix: wrap interactive content in Button (which provides focus participation by default) or apply .focusable() explicitly.

Focus traps. A view that accepts focus but provides no path out (no left/right/up/down sibling that’s focusable, no escape via Menu button) leaves the user stuck. Fix: every focus context should have a documented exit path. The .focusSection() pattern helps because it gives the engine a unit to escape to.

Default focus on the wrong element. A movie detail screen that opens with focus on Back instead of Play is friction the user pays on every visit. Fix: declare .prefersDefaultFocus(in:) on the primary action.

Custom focus effects that aren’t accessible. A focus ring that’s just a 1pt color border at low contrast fails accessibility. The system focus effect is high-contrast and motion-tested; custom replacements need the same care. The cluster’s Accessibility as platform post covers the broader principle.

When tvOS Earns The Slot

The cluster’s Apple Platform Matrix argued that tvOS is the platform with the smallest install base relative to iOS, and apps need a real “lean back” or “couch-mode” use case to justify the engineering investment. The focus engine is part of that investment: a tvOS app that doesn’t honor the focus vocabulary feels like an iPad app stretched across a TV. The investment is real because the API surface is real; the engineering work is meaningful because the engine actually decides where focus goes.

Apps that earn their tvOS slot tend to share three properties: 1. Content consumed at TV-watching distance. Streaming, photo slideshows, controller-driven games. 2. Sparse interaction model. A few primary actions per screen, navigated with directional input. 3. Lean-back use case. The user is on a couch, possibly multitasking with another device, possibly half-watching.

For apps in those categories, the focus-engine investment is right. For apps that don’t fit (productivity tools, fine-grained creative apps, anything text-input-heavy), the right call is to skip tvOS, as the matrix post recommends.

What This Pattern Means For tvOS Apps

Three takeaways.

1. Build focus intent into the layout, not into a post-hoc fix. Where will the user start? Where can they go from there? What’s the primary action? Designing a screen on tvOS starts with the focus flow, not the visual composition. The visual follows.

2. Use .focusSection() aggressively for any region with internal structure. The default geometric navigation is often wrong for grids, sidebars, tab bars. The section modifier is small and the difference is large.

3. Keep the system focus effect unless you have a real reason to replace it. Custom focus visuals are real engineering work plus accessibility work plus testing across all themes. The system effect is the right default; reach for .focusEffectDisabled() only when the design genuinely needs a custom treatment.

The full Apple Ecosystem cluster: typed App Intents; MCP servers; the routing question; Foundation Models; the runtime vs tooling LLM distinction; three surfaces; the single source of truth pattern; Two MCP Servers; hooks for Apple development; Live Activities; the watchOS runtime; SwiftUI internals; RealityKit’s spatial mental model; SwiftData schema discipline; Liquid Glass patterns; multi-platform shipping; the platform matrix; Vision framework; Symbol Effects; Core ML inference; Writing Tools API; Swift Testing; Privacy Manifest; Accessibility as platform; SF Pro typography; visionOS spatial patterns; Speech framework; SwiftData migrations; what I refuse to write about. The hub is at the Apple Ecosystem Series. For broader iOS-with-AI-agents context, see the iOS Agent Development guide.

FAQ

Does .focusable() work on iOS?

Yes, but its behavior on iOS targets keyboard and pointer interactions (Bluetooth keyboard, iPadOS pointer, iPad Magic Keyboard), not the focus-engine-driven navigation tvOS uses. The same code can be used cross-platform; the user-facing interaction differs. On tvOS, .focusable() is the primary path. On iOS, it’s a supplemental affordance for accessibility.

What’s the difference between .focusable() and Button?

Button is a higher-level construct that includes focusability, action handling, the system button style, and accessibility traits. .focusable() is the low-level marker that just makes a view a focus target. Use Button when the view is logically a button; use .focusable() when you’re building a custom interactive view (a poster card, a tile in a grid) that doesn’t fit the button mental model.

Can I have multiple .prefersDefaultFocus declarations?

Yes, scoped by @Namespace. Each focus scope can have its own preferred default. The pattern is right for nested contexts (a popover within a screen, a tab within a sidebar): each scope picks its own initial focus.

How do I handle focus in a list with many items?

Lists in SwiftUI are focusable by default; the engine handles up/down navigation through cells automatically. For custom list-like layouts, wrap each cell in a Button or apply .focusable(), then place the entire list inside a .focusSection() so the engine treats the list as a unit relative to other UI regions.

What does the Menu button do in the focus model?

The Siri Remote’s Menu button is the dismiss/back action across tvOS. It pops the navigation stack, exits modals, returns to the parent context. SwiftUI handles it automatically through NavigationStack and standard modal dismissal; apps don’t typically intercept it. For custom dismissal logic, the onExitCommand view modifier captures the press.

How does this relate to the cluster’s other platform posts?

tvOS focus engine is the platform-specific navigation surface, parallel to visionOS’s gaze-and-pinch (covered in visionOS spatial patterns) and iOS’s tap-and-scroll. Each platform has its own input metaphor; the cluster’s Apple Platform Matrix post argues that platform inclusion requires honoring that metaphor, and the focus engine is what tvOS demands.

References