> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joyfill.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Upload Handling

The Joyfill SDK provides comprehensive image upload functionality through image fields, supporting both single and multiple image uploads with flexible handling options.

**Architecture Overview**

When users interact with image fields, the SDK triggers onUpload events that your application must handle by implementing the FormChangeEvent protocol.

**Parameters**

| Parameter     | Type                | Description                                         |
| ------------- | ------------------- | --------------------------------------------------- |
| fieldEvent    | FieldIdentifier     | Contains metadata about the field requesting upload |
| target        | String?             | The target action for the upload                    |
| multi         | Bool                | Whether multiple files are allowed                  |
| schemaId      | String?             | Schema identifier for table/collection fields       |
| parentPath    | String?             | Path to parent field for nested structures          |
| rowIds        | \[String]?          | Array of row IDs for table fields                   |
| columnId      | String?             | Column identifier for table fields                  |
| uploadHandler | (\[String]) -> Void | Callback function to provide uploaded URLs          |

**Detailed Example**

For a complete working example with image picker implementation, see:

[**ImageReplacementTest.swift**](https://github.com/joyfill/components-swift/blob/main/JoyfillSwiftUIExample/JoyfillExample/ImageReplacementTest.swift) - Demonstrates image upload with URL replacement

**Common Usage Patterns**

**Pattern 1: Immediate Server**

```swift theme={null}
func onUpload(event: UploadEvent) {
    // 'urls' can come from your gallery, camera, or any other source
    let urls: [String] = []
    event.uploadHandler(urls)
}
```

**Pattern 2: Programmatic Image Replacement**

You can replace images after upload using the replaceImageURL method:

```swift theme={null}
func onUpload(event: UploadEvent) {
        // 'localURLs' can come from your gallery, camera, or any other source
        let localURLs: [String] = []
        // Show images immediately
        event.uploadHandler(localURLs)
        
        // Upload and replace in background
        for localURL in localURLs {
            uploadToServer(localURL) { serverURL in
                documentEditor?.replaceImageURL(
                    newURL: serverURL,
                    url: localURL,
                    fieldIdentifier: event.fieldEvent
                )
            }
        }
    }
```

**Flow:**

1. User taps image field → SDK creates UploadEvent
2. Your onUpload handler receives the event
3. You present image picker/camera
4. Process selected images (resize, upload to server, etc.)
5. Call event.uploadHandler(\[urls]) with final URLs
6. SDK updates the form with the provided URLs