The Xcode canvas shows no SwiftUI preview
The canvas is empty or shows no preview for the fileShort 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.
Fix it fast
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/*.swift2Match what you see, then jump to its fix
- 1
grep finds no #Preview in the file you are looking atThe file has no preview macro, or the canvas is closedFix - 2
The 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
The preview is slow to appear, or its view model starts network calls or reads from diskThe preview builds expensive objects or real data sourcesFix
- 1
What does the error look like?
The canvas is empty or shows no preview for the fileThe 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.swift2Fix
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 toolbarConfirmed by developer.apple.com
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" *.swift2Fix
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 controlConfirmed by developer.apple.com
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.swift2Fix
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 offConfirmed by developer.apple.com
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
UserDefaults logs 'Failed to read values in CFPrefsPlistSource' for an app group
Settings saved by the app are not visible to its extension, widget or sibling app that share the group
This log comes from the preferences system when UserDefaults is opened for an app group's suite.
3 causes, each with a fixMobile apps
iOS app crashes: Google Maps SDK must be initialized via provideAPIKey
Google Maps SDK for iOS must be initialized via [GMSServices provideAPIKey:...] prior to use
The Maps SDK throws this when a Maps object is created before GMSServices.provideAPIKey has run.
3 causes, each with a fixMobile apps
UIKit app crashes because it cannot find the storyboard
Could not find a storyboard named 'Main' in bundle NSBundle
UIStoryboard throws this exception when no storyboard file with that name exists in the bundle it searches.
3 causes, each with a fixMobile apps
Firebase on iOS asks for the FCM token before APNs has given one
Be sure to re-retrieve the FCM token once the APNS device token is set.
The Firebase Messaging SDK needs the APNs device token from iOS before it hands out an FCM token.
3 causes, each with a fixMobile apps
A test push from the Firebase console never shows up on the iPhone
didReceiveRegistrationToken prints a token, yet no notification arrives
When a console message is accepted but the iPhone stays silent, the break is between Firebase and APNs or inside the app.
4 causes, each with a fixMobile 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