File upload builder for documents, media, and attachments. This is the only builder that does not extend BaseFieldBuilder.
- Has its own upload-focused fluent API:
accept(),maxSize(),multiple(),preview(),source(),resize() render(),transform(), and the conditional helpers fromBaseFieldBuilderare not available on this builder- Platform differences are handled by the renderer - the schema keeps the business contract
Defaults, inheritance & field methods
This builder has its own upload-focused fluent API rather than the full BaseFieldBuilder surface.
Defaults:
- defaultValue is
nullfor single-file mode, or[]after callingmultiple() - accepted types default to any file type
- drag & drop is enabled on web by default
- file previews are off by default
File-builder methods:
| Method | Type | Description |
|---|---|---|
label(text) | text: string | Sets the field label rendered above the uploader. |
required(message?) | message?: string | Marks file selection as mandatory. Default message: "Please select a file.". |
hint(text) | text: string | Adds helper copy below the uploader. |
disabled(value = true) | value?: boolean | Disables or re-enables the uploader. |
hidden(value = true) | value?: boolean | Hides or shows the uploader. |
accept(types) | types: string[] | Restricts accepted MIME types. Supports wildcards like image/*. Validated client-side against the actual file type. |
maxSize(bytes) | bytes: number | Maximum size per file in bytes. Validation runs against every file when multiple() is enabled and rejects with a human-readable MB message. |
multiple(max = 10) | max?: number | Enables multi-file mode, sets the maximum allowed file count, and switches the default value from null to []. |
preview(height = 160) | height?: number | Enables image previews and sets their preview height in px. |
source(type) | 'gallery' | 'camera' | 'documents' | 'all' | Native-only: which picker to open. all (default) shows an action sheet so the user can choose. Web ignores this since the browser file dialog handles all sources. |
withBase64() | () => this | Requests base64 encoding alongside the file payload - needed for upload APIs that expect inline payloads instead of multipart streams. |
resize(maxWidth, maxHeight, quality = 0.9) | number, number, number? | Native-only: auto-resize images before they enter the form value. Useful to keep mobile uploads under the size limit before they hit the network. |
allowVideo() | () => this | Native-only: includes video files in the gallery/camera picker. Web relies on accept() instead. |
noDragDrop() | () => this | Web-only: disables the drop-zone surface and shows just the browse button. |
dragLabel(label) | label: string | Web-only: customizes the drop-zone copy. Defaults to "Drag & drop a file here, or click to browse". |
visibleWhen(field, value?) / visibleWhenNot / visibleWhenTruthy / visibleWhenFalsy / visibleWhenAny | field | predicate | Conditional visibility rules. Same shape as the BaseFieldBuilder helpers - show the uploader only when another field matches a value, is truthy/falsy, or matches any of several pairs. |
requiredWhen(field, value?) / requiredWhenAny | field | predicate | Conditional required rules so the uploader only becomes mandatory when another field hits a given state. |
disabledWhen(field, value?) | field | predicate | Conditional disabled rule so the uploader locks based on another field. |
resetOnHide() / keepOnHide() / clearOnHide() | () => this | Controls what happens to the selected file(s) when the field becomes hidden by a visibility rule. |
Static presets - shortcuts that pre-configure common upload flows:
| Method | Type | Description |
|---|---|---|
FileFieldBuilder.profilePhoto(label?) | label?: string | Profile photo preset: JPG/PNG/WebP, 5 MB cap, gallery source, preview enabled, image resized to 1024×1024 at 0.85 quality. |
FileFieldBuilder.document(label?) | label?: string | PDF-only document preset, 10 MB cap, document picker source. |
FileFieldBuilder.attachments(label?, max = 5) | label?: string, max?: number | Multi-attachment preset accepting images and PDFs, 10 MB cap each, preview enabled, drag zone hint adapts to the max. |
FileFieldBuilder.spreadsheet(label?) | label?: string | CSV/XLS/XLSX import preset, 20 MB cap, document picker source. |
Base-builder relationship:
- See Base field builder for the shared surface most other builders inherit
field.file()ships its own conditional helpers (visibleWhen,requiredWhen,disabledWhen,resetOnHide, …) that mirror the BaseFieldBuilder shape, so it integrates with the same conditional logic as every other field- It does not expose
render(),transform(), or the value-coercion helpers because it does not extend the fullBaseFieldBuildersurface
Recipes
Patterns that showcase file-specific strengths.
Avatar with preview
Avatar.tsxtsx
| 1 | const schema = { |
| 2 | avatar: field.file('Avatar') |
| 3 | .accept(['image/jpeg', 'image/png']) |
| 4 | .maxSize(5 * 1024 * 1024) |
| 5 | .preview(120) |
| 6 | .required('Please upload a photo.'), |
| 7 | } |
Mobile document capture
IdentityCard.tsxtsx
| 1 | const schema = { |
| 2 | identityCard: field.file('Identity card') |
| 3 | .accept(['image/jpeg', 'image/png', 'application/pdf']) |
| 4 | .source('documents') |
| 5 | .withBase64() |
| 6 | .maxSize(10 * 1024 * 1024), |
| 7 | } |
Multi-attachment with drag zone
Attachments.tsxtsx
| 1 | const schema = { |
| 2 | attachments: field.file('Attachments') |
| 3 | .multiple(5) |
| 4 | .accept(['application/pdf', 'image/png']) |
| 5 | .dragLabel('Drop files here or click to browse'), |
| 6 | } |
Optimized product media
ProductMedia.tsxtsx
| 1 | const schema = { |
| 2 | productPhotos: field.file('Product photos') |
| 3 | .accept(['image/jpeg', 'image/png', 'video/mp4']) |
| 4 | .resize(1600, 1600, 0.85) |
| 5 | .allowVideo() |
| 6 | .multiple(10), |
| 7 | } |
Click-only (no drag)
DocumentsOnly.tsxtsx
| 1 | const schema = { |
| 2 | documents: field.file('Documents') |
| 3 | .accept(['application/pdf']) |
| 4 | .noDragDrop(), |
| 5 | } |