Upload
Upload uploads one or more files and binds returned file metadata to the Form. It participates in the state, validation, and submission boundary of its Form.
1. When to use it
Typical uses:
- Attachments and evidence
- Image or document uploads
- File input with format, count, and size limits
2. Add and configure
- Add Upload to the Fields slot of a Form Section.
- Set a stable, unique Field Key / Name that matches the backend DTO property.
- Configure the component properties below, then add Required, Help Text, Full row, or conditions as needed.
- Check the initial value and layout in Design Preview, then use Form Validate / Submit to test the full data path.
3. Main properties
| Property | Purpose |
|---|---|
| Multiple | Enables or disables this behavior. |
| Form Upload / Upload URL | Defines where selectable data comes from and how it is mapped. |
| Component Style | Controls how the field is displayed in Design Preview and Runtime. |
| Upload Format Filter | Limits the allowed count, length, or value range. |
| Upload Count / Size Limit | Limits the allowed count, length, or value range. |
| Enable Image Cropping | Enables or disables this behavior. |
Common properties such as Field Key, Required, Help Text, Full row, and Visible When come from the Form field contract. The table highlights the settings most relevant to Upload.
4. Form value and backend contract
Submitted value: An array of file metadata. Exact properties come from the upload response and mapping, not a browser binary object.
[
{"id": "file-1024", "name": "evidence.pdf", "url": "/files/file-1024"}
]
The example shows the data shape only. The API must still validate type, range, and authorization against its business DTO.
5. Validation, conditions, and interactions
Every field can use Form properties such as Required, Visible When, Disabled When, Required When, Dependencies, and Clear When Hidden. Conditions improve interaction but never replace backend validation or authorization.
Component capabilities: Supports setValue; the upload-success script and upload state handle server responses.
6. Recommendations
Recommendations: Fix the request and response JSON contract before configuring the field, then test array items, file metadata, and server error paths end to end.
Return to the Form overview for layout, validation, submission, drafts, and backend protocol guidance.