Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

The Xcode canvas shows no SwiftUI preview

ErrorThe canvas is empty or shows no preview for the file

Short answer

Xcode shows a preview only for code inside a #Preview macro, and only when the canvas is open. If the canvas is open and still empty or failing, the preview probably builds the view without what it needs: a binding, a state value or an environment object. Give the preview that data, and keep real network or disk work out of it.

  • Applies to Xcode 26, SwiftUI, Swift 6
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check the file for a preview macro and open the canvas with Show Canvas in the upper-right corner of the toolbar. If the macro exists and the canvas is open, move to the second cause.

    grep -n "#Preview\|PreviewProvider" Sources/*.swift
  2. 2Match what you see, then jump to its fix

    1. 1grep finds no #Preview in the file you are looking atThe file has no preview macro, or the canvas is closedFix
    2. 2The view takes a @Binding or reads an @Environment object, and the preview creates it with no arguments or no injected valueThe view needs a binding, state or environment value the preview does not give itFix
    3. 3The preview is slow to appear, or its view model starts network calls or reads from diskThe preview builds expensive objects or real data sourcesFix

What does the error look like?

  • The canvas is empty or shows no preview for the file
  • The preview is stuck loading or fails when the view reads a binding or environment object

Cause 1 of 3

The file has no preview macro, or the canvas is closed

1Check

Apple says Xcode shows previews in the canvas for views configured inside a #Preview macro, and the canvas is opened with Show Canvas in the toolbar. A file without that macro has nothing to display.

grep -n "#Preview" ContentView.swift

2Fix

Add a #Preview block that creates your view, then open the canvas.

struct ContentView: View {
    var body: some View { Text("Hello") }
}

#Preview {
    ContentView()
}

3Verify

The canvas lists the preview and shows the view.

# manual: click Show Canvas in the toolbar

Confirmed by developer.apple.com

Did this fix it?

Cause 2 of 3

The view needs a binding, state or environment value the preview does not give it

1Check

A preview builds your view on its own, so anything the parent normally supplies has to be supplied in the preview. Apple's guide shows two ways: tag a dynamic property with @Previewable inside the #Preview and pass its binding, and inject objects with the environment function.

grep -n "@Binding\|@Environment" *.swift

2Fix

Create the missing value inside the preview and hand it to the view. Prefer views that take plain values over views that fetch data.

#Preview {
    @Previewable @State var isPlaying = true
    PlayButton(isPlaying: $isPlaying)
}

3Verify

The canvas shows the control and responds to taps in live mode.

# manual: run the preview in the canvas and tap the control

Confirmed by developer.apple.com

Did this fix it?

Cause 3 of 3

The preview builds expensive objects or real data sources

1Check

Apple notes that objects which make network calls, access the disk or take effort to set up make previews take longer to load, and that views taking only the data they need are easier to preview.

grep -n -B1 -A6 "#Preview" ContentView.swift

2Fix

Pass the view small sample values, or create one shared sample object with a PreviewModifier and reuse it across previews.

struct SampleData: PreviewModifier {
    static func makeSharedContext() async throws -> AppState {
        AppState()
    }
    func body(content: Content, context: AppState) -> some View {
        content.environment(context)
    }
}

#Preview(traits: .modifier(SampleData())) {
    ComplexView()
}

3Verify

The preview loads quickly and makes no network request.

# manual: watch the canvas load with the network off

Confirmed by developer.apple.com

Did this fix it?

How do I stop it coming back?

  • Add a #Preview to every new view file the moment you create it.
  • Build views from simple values so a preview can create them in one line.
  • Keep networking and disk access in model objects that previews replace with sample data.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

InstanceID token() no longer works in a Swift Firebase app

Instance ID calls fail to compile after upgrading Firebase to 8.0.0 or later

Firebase removed the Instance ID dependency from Messaging in 8.0.0, so InstanceID.instanceID() calls no longer belong in a current app.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.