Add Spreadsheet Uploads in SwiftUI

How to Add CSV & Excel Uploads to SwiftUI Apps with CSVBox

If you’re building a SwiftUI app that manages records — a CRM, analytics dashboard, inventory tracker, or internal tool — users will soon ask to import spreadsheets. As of 2026, adding a robust spreadsheet import flow remains a common engineering requirement: how to upload CSV files in 2026, validate them, map columns, and surface actionable errors.

SwiftUI provides great UI primitives, but it does not include a complete spreadsheet import UX (parsing Excel, column mapping, validation, map UI). This guide shows a pragmatic integration pattern using CSVBox: an embeddable, hosted importer that returns structured, validated JSON to your app. You’ll get a small local HTML embed, a WKWebView wrapper, and a safe way to handle the import callback natively.

Who this is for

SwiftUI developers adding spreadsheet import to iOS or macOS apps
Product and engineering teams who want a polished import UX fast
Teams that prefer a hosted, low-code importer and native callbacks

Why use a hosted importer like CSVBox

Accepts .csv and .xlsx files with parsing handled server-side
Hosted UI for header preview, column mapping and validation
Returns cleaned JSON via client callback or webhook for server processing
Embeds easily into mobile apps using a small WebView wrapper

Top search phrases this article answers: how to upload CSV files in 2026, CSV import validation, map spreadsheet columns, handle import errors, SwiftUI Excel uploader.

Prerequisites

Xcode 14+ (project must support SwiftUI)
Deployment target iOS 14+ (or macOS equivalent)
A CSVBox account and an importer template configured in the CSVBox dashboard

Create an importer template on CSVBox

Sign in to https://app.csvbox.io
Create a new importer template and define expected fields, header names, and validation rules
Save and copy your TEMPLATE_ID

Tip: Templates define the parsing rules and validation that CSVBox applies to every uploaded spreadsheet.

Generate the embed snippet CSVBox exposes a lightweight widget script you can embed from importer HTML. The snippet wires up callbacks (onComplete, onCancel) so your app receives the normalized import result.

Example (embed inside your local HTML file): ” }, onComplete: function(result) { // result is a JSON-serializable object with cleaned rows and metadata window.webkit.messageHandlers.csvbox.postMessage(result); }, onCancel: function() { window.webkit.messageHandlers.csvbox.postMessage({ status: “cancelled” }); } });

  document.getElementById("csvbox-btn").addEventListener("click", function () {
    csvbox.open();
  });
</script>

Notes

Use your real TEMPLATE_ID and real user metadata if you want CSVBox to associate uploads with a user.
Posting the result object directly (instead of JSON.stringify) allows WKWebView to deliver native payload types that are easier to decode in Swift.

Add a local importer.html to your Xcode project Place an importer.html file in your app bundle and ensure it’s included in your target membership.

Example importer.html:

    <script>
      const csvbox = new CSVBox("YOUR_TEMPLATE_ID", {
        user: {
          id: "ios-user-001",
          name: "iOS Tester",
          email: "test@iosapp.com"
        },
        onComplete: function(result) {
          // send a JSON-serializable object to the native app
          window.webkit.messageHandlers.csvbox.postMessage(result);
        },
        onCancel: function() {
          window.webkit.messageHandlers.csvbox.postMessage({ status: "cancelled" });
        }
      });

      document.getElementById("csvbox-btn").addEventListener("click", function () {
        csvbox.open();
      });
    </script>
  </body>
</html>

Important: Enable Target Membership for importer.html so it is bundled in your app. When loading local HTML that references external script URLs, the WKWebView will fetch them over HTTPS as long as App Transport Security allows it (default iOS settings permit standard HTTPS hosts).

Implement a SwiftUI WKWebView wrapper Use a UIViewRepresentable (iOS) / NSViewRepresentable (macOS) wrapper to host the HTML and receive messages from the widget.

Swift example (iOS) with robust message handling: import SwiftUI import WebKit

struct CSVBoxWebView: UIViewRepresentable {
    class Coordinator: NSObject, WKScriptMessageHandler {
        var parent: CSVBoxWebView

        init(parent: CSVBoxWebView) {
            self.parent = parent
        }

        func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
            // message.body can be Dictionary, Array, String, Number, or NSNull
            if message.name == "csvbox" {
                // Normalize to Data for JSON decoding where possible
                if let dict = message.body as? [String: Any] {
                    parent.onUploadComplete(.dictionary(dict))
                } else if let arr = message.body as? [Any] {
                    parent.onUploadComplete(.array(arr))
                } else if let str = message.body as? String {
                    parent.onUploadComplete(.string(str))
                } else {
                    parent.onUploadComplete(.unknown)
                }
            }
        }
    }

    enum UploadPayload {
        case dictionary([String: Any])
        case array([Any])
        case string(String)
        case unknown
    }

    var onUploadComplete: (UploadPayload) -> Void

    func makeCoordinator() -> Coordinator {
        Coordinator(parent: self)
    }

    func makeUIView(context: Context) -> WKWebView {
        let contentController = WKUserContentController()
        contentController.add(context.coordinator, name: "csvbox")

        let config = WKWebViewConfiguration()
        config.userContentController = contentController

        let webView = WKWebView(frame: .zero, configuration: config)

        if let url = Bundle.main.url(forResource: "importer", withExtension: "html") {
            // allow read access to the containing directory
            webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())
        } else {
            // fallback: load a blank page to avoid a crash
            webView.loadHTMLString("<html><body>Importer missing</body></html>", baseURL: nil)
        }

        return webView
    }

    func updateUIView(_ uiView: WKWebView, context: Context) {}
}

Notes on the wrapper

Use allowingReadAccessTo: url.deletingLastPathComponent() to ensure any relative resources can load.
The coordinator converts WKScriptMessage types into an UploadPayload enum so your SwiftUI view can switch on the result.

Use the WebView in your SwiftUI view Render the importer and handle results. Parse the returned payload into your native models or forward to your backend.

Example: struct ImportView: View { @State private var importInfo: String?

    var body: some View {
        VStack(spacing: 20) {
            Text("Import Spreadsheet")
                .font(.title)

            CSVBoxWebView { payload in
                switch payload {
                case .dictionary(let dict):
                    // Convert to JSON for logging or decoding into structs
                    if let data = try? JSONSerialization.data(withJSONObject: dict, options: []),
                       let json = String(data: data, encoding: .utf8) {
                        importInfo = json
                        print("CSVBox result: \(json)")
                    }
                case .array(let arr):
                    if let data = try? JSONSerialization.data(withJSONObject: arr, options: []),
                       let json = String(data: data, encoding: .utf8) {
                        importInfo = json
                        print("CSVBox result array: \(json)")
                    }
                case .string(let s):
                    importInfo = s
                    print("CSVBox result string: \(s)")
                case .unknown:
                    importInfo = "Unknown payload"
                }
            }
            .frame(height: 420)

            if let info = importInfo {
                ScrollView {
                    Text(info)
                        .font(.footnote)
                        .padding()
                }
                .frame(maxHeight: 220)
            }
        }
        .padding()
    }
}

Common issues & fixes

HTML file not loading
- Confirm importer.html is added to the app target and that its resource path is correct. Use url.deletingLastPathComponent() for allowingReadAccessTo when loading local files.
JavaScript callback not received
- Ensure the name you add to WKUserContentController matches the name used in postMessage (here: “csvbox”).
- If you post a raw JS object, WKWebView will deliver it as native types; handle both String and Dictionary cases in Swift.
Parsing/decoding errors in Swift
- Inspect the raw payload with JSONSerialization before decoding into typed models. Start by printing the raw payload to the console.
- If the JS code uses JSON.stringify, decode the String as JSON in Swift. If it posts an object, handle it as a Dictionary directly.

What happens behind the scenes (import flow)

User opens the CSVBox UI in the embedded web view (file → map → validate → submit).
CSVBox parses and validates rows against your template rules.
Valid rows are returned; invalid rows include error reasons for per-row feedback.
The onComplete callback sends the normalized JSON to the WebView, which your native code receives via WKScriptMessage and processes (persist locally, submit to backend, or display errors).
Optionally use CSVBox webhooks for server-side processing or to receive a final import audit.

Developer controls and best practices (2026)

Validate payload shape in Swift before persisting: guard required fields exist and types match.
Use webhooks for heavy processing or to keep client logic minimal.
Surface row-level validation back to users so they can correct and re-upload — this improves import success rates.
Keep user metadata minimal but consistent (id/email) so CSVBox audit logs map imports to your users.

Next steps

Customize your template at https://app.csvbox.io to tune validation and fields
Convert the returned payload into native Swift structs with Codable after verifying the shape
Add retry and error UI flows that guide users to fix invalid rows
Optionally wire CSVBox webhooks to your backend for automated post-processing

Add Spreadsheet Uploads in SwiftUI

How to Add CSV & Excel Uploads to SwiftUI Apps with CSVBox

Related Posts