media-field
The media-field component allows users to upload images, videos, or files, either standalone or within a form. It supports:
Preview and thumbnails, with built-in delete controls
Single or multiple selection
Cropping and quality settings
Size limits and type filtering
Configuration options
The
media-fieldcan only be used in a jig.default.The
media-fieldrequires a datasource to store the files, you can configure one of the Data Providers for this.Conversions allow you to determine the format the files are stored in and loaded from the datasource.
Jigx recommends storing images and files using Dynamic files, where the files are physically stored in Amazon S3.
Some properties are common to all components, see Common component properties for a list and their configuration options.
instanceId
Provide a unique identifier for the media-field component.
label
Label is displayed as a placeholder if there is no value provided. Use this property to provide a value that will guide the user to identify what must be uploaded, such as Upload file or Upload a video.
mediaType
By default the value is set to image. Configure filters to restrict media types based on your app’s requirements, for example, only allow document files DOC, PDF or plain text. Multiple options can be listed to provide greater scope of filtering, i.e. PDF and DOC files. The following options are available for selection: 1) any is for files of any extension such as pdf, jpeg, png, mpeg, txt, or docx. Set to any allows you to take a picture, record a video, select an image or video from the library, or select a document. Using mediaType: any is recommended when uploading multiple media files as it caters for any file type. 2) csv - select CSV files. 3) doc - select DOC or DOCX files. 4) image - used to take a picture or select from the image library. 5) imageAndVideo - take a picture, record a video or select an image or video from the library. 6) pdf - select PDF files. 7) plainText - select plain text files. 8) ppt - select PPT or PPTX files. 9) video - record a video or upload one from the library. 10) xls - select XLS or XLSX files.
intialValue
The initialValue property populates the media-field with the specified files when the field first loads, allowing you to preset default media so users don’t need to select files manually. To update the media, simply tap the media-field and upload a new selection. Note that using the reset-state action will not clear the field entirely; it always restores the media-field back to its configured initialValue.
imageCropping
You can set any of the following with imageCropping :
isEnabled- allows you to crop an image.height- maximum allowed is 5000px.width- maximum allowed is 5000px.isFreeStyleCropEnabled- when set totrueit supports custom cropping to change the size or aspect ratio of an image.
imageQuality
Image quality after compression (from 0 to 100, where 100 is the best quality). On iOS, values larger than 80 don't produce a noticeable quality increase in most images, while a value of 80 will reduce the file size by about half or less compared to a value of 100. Default: 100 (Android)/ 80 (iOS).
isMultiple
Set to true allows for multiple files to be added. Set to false allows for a single file.
maximumFileSize
maximumFileSize =6 * 1024 * 1024 by default. Set the value to none if no size evaluations must be performed. File size format is in bytes. Applies to images and videos.
action.open-media-picker
Configure the open-media-picker action to either launch the camera immediately so you can capture a photo or video, or open the media library to select existing files and return their paths.
Working with media files as data
When using a media-field in Jigx, storing and loading certain files, such as images or videos, must be configured through a datasource such as Dynamic Files, REST, or SQL. The selected datasource determines how the files are stored, retrieved, and managed. Additional configuration may be required, such as specifying file paths, formats, or storage references, to ensure compatibility across devices and use cases, including offline access or multi-platform viewing. Proper configuration also helps optimize storage space by avoiding duplication, compressing media where possible, and ensuring that only required media is retained. The table below outlines the additional configuration needed for each datasource type.
Dynamic Data with Dynamic Files
Use action.execute-entities with DATA_PROVIDER_DYNAMIC , including the file property. Files are stored in Amazon S3. See Dynamic files for setup.
Files are retrieved via a datasource query using DATA_PROVIDER_DYNAMIC. The file is linked to the record and can be accessed based on query results.
REST
Use action.execute-entities with conversions in the Jigx function to transform local-uri to a format suitable for uploading to your backend (e.g., base64, buffer). Use a create or save method in the DATA_PROVIDER_REST to send the data.
On loading, convert the backend format (e.g., buffer or base64) back into a local-uri in the Jigx function, so the file can be displayed. Files are retrieved via a datasource query using DATA_PROVIDER_REST.
SQL
Use action.execute-entities with conversions in the Jigx function to transform local-uri into a suitable format (e.g., base64 or buffer) for storing in the database. Use the create or save method in the DATA_PROVIDER_SQL to send the data.
On load, convert the stored SQL file format back into a local-uri in the Jigx function, to display in the media-field. Files are retrieved via a datasource query using DATA_PROVIDER_SQL.
iOS device
When storing files from iOS, use the convertHeicToJpg property to ensure compatibility across devices.
iOS reads standard file formats like JPG or PNG via local-uri. If the file is HEIC, conversion may be required for cross-device viewing.
Android device
Store media using one of the data providers; ensure files are correctly referenced from their captured local-uri. No special conversion needed for common formats like JPG or PNG.
Android can read from local-uri. Ensure file paths are valid. Cross-device issues may occur with platform-specific formats if not converted (e.g., HEIC).
Considerations
To discard selected or recorded images, videos or files before submitting them, click on the media thumbnail at the bottom of the selection modal.
An image, video, or file can be referenced for upload from a datasource, for example, in the
initialValueproperty.If a file can’t be displayed using the
initialValueproperty, the app will show an icon with the file’s name instead. This usually happens because Android and iOS use different file path formats. To ensure images display correctly on all devices, convert iOS HEIC images to JPG before saving them. See conversions for more information.When uploading multiple files, the media-field displays up to three files by default. If more than three files are selected, the third file is overlaid with a + and the count of additional files (e.g., +2) to indicate how many are not shown. While the total number of files to be added is displayed in the top-right corner of the media-field.
Files captured using the
media-fieldcomponent can be saved to Dynamic Files by assigning them to thefileproperty of a dynamic data entity, enabling seamless upload and storage in Amazon S3.You can use the open-media-picker action to invoke the
media-fieldcomponent to either open the device's camera when tapping the action button, or to select media files and output selected paths.
Examples using media-field configurations
Restrict or filter the upload of media file types
This example shows a form for a new employee, configured with a media-field component that allows the employee to upload their signed employment contract. File formats are restricted to DOC and PDF. The media picker opens and displays only PDF and DOC files for selection.
Upload image & use freestyle cropping
This component uploads an image using the mediaType: image property. Clicking on the paperclip icon will display a menu where you can choose to upload an existing image from your device or use the camera to take a new image. After selecting or capturing the image, and cropping the image to the specified size, the media-field is first validated, then the upload button becomes enabled. Pressing the Upload image button at the bottom will trigger an action to create an entry with the image.
Examples: See the full example in GitHub.
Upload multiple files
In this example we set the isMultiple property to true which allows for the selection of multiple media to be uploaded and MediaType to any which caters for images, videos and documents. The selected media display as thumbnails at the bottom of the modal. Discard media by pressing on the thumbnail, the media is deleted.
Upload video
In this example multiple videos are uploaded, using the mediaType: video and isMultiple: true properties. Select videos from the library or record videos to be uploaded. Tap the + icon in the bottom left corner to add multiple videos. The execute-entities action uploads the videos and the metadata configured under data to the required datasource.
Example: See the example in GitHub.
Upload image or video
In this example multiple images and videos are uploaded, using the mediaType: imageAndVideo and isMultiple: true properties. Select images and videos from the library, take a picture or record videos to be uploaded. Tap the + icon in the bottom left corner to add multiple images and videos. The execute-entities action uploads the images, videos and metadata to the required datasource.
Example: See the example in GitHub.
Example using the media-field in an action
Use open-media-picker action to capture an image
In this example, the button opens the media-picker. The configuration is set to take a picture or choose from a library. The image is saved to the local database.
Examples of saving & loading media-field as data
Upload image using Dynamic files
In this example, an expense claim form allows you to capture expense details and upload a file, such as a slip or invoice. The media-field is configured to accept any file type, with a maximumFileSize set to ensure files remain within acceptable limits. An execute-entity action creates the record in the datasource and links the uploaded file to the record by using the create method, with the file specified in the localPath property
Upload images using REST
In this example the REST APIs POST operator is used to store images. A Jigx function with an inputTransform is used to capture the image metadata. Configuring the conversion property ensures that the images are uploaded in the correct format to the REST service.
See the example in Upload product images (POST) topic to understand how to upload files using the REST data provider.
Use intialValue to show multiple images using REST
This example shows how multiple images can be loaded in the media-field using the intialValue property. Take note of the following configuration:
The
initialValueuses a datasource to return images. A local datasource ensures the images from the REST endpoint are stored locally on the device, for offline and performance reasons. The local datasource has aqueryParameterrestricting the images returned to be for the specific customer.To store images on upload in the correct format a
conversionis set on the REST POST function, converting the file from local-uri to base64. Added to this theconvertHeicToJpgproperty is set totrue, which allows the image to be viewable on iOS and Android.The load images into the media-field, requires images to be in
local-uriformat, a conversion is set in the REST GET function, converting the file from base64 to local-uri to display the image.When clicking on the
media-fieldto add additional images the intial images are loaded in the field. Depending on the function used, for example POST, if the images are not cleared or removed, the initial images will be uploaded as new images, creating duplicates. Using a PATCH or PUT function could avoid duplicates.
Convert files in SQL function
Jigx stores files as local files on the device and returns the file's URI as the default value. When saving these files to a datasource, you must convert files from the local-uri to base64, data-uri, or buffer. The opposite is true when handling the files returned from the datasource, you need to convert them from their saved state (base64, data-uri, or buffer) to a local-uri. In this example we upload a profile photo and convert from local-uri on the device to buffer for storage in SQL and then get the photo back from SQL and convert it from buffer to local-uri to display the photo as an avatar in a list. See File handling for more information.
See also
Last updated
Was this helpful?