doc: add documentation for the Upload component by laurenic0l · Pull Request #981 · webforj/webforj-documentation

laurenic0l · 2026-05-28T02:32:37Z

Adds the documentation article and demos for the new inline Upload component

Covers:

Basics + when to use vs. FileUploadDialog
Picking files: selection mode, picker source, filters, drop zone
Validation and limits + server-side validation note
Upload behavior: auto upload, auto clear, programmatic actions
Mobile capture
Native file system access
Customizing the layout: presets, part visibility, default slot
Themes
Events
Internationalization
Styling

- docs/components/upload.md covering basics, picker behavior, validation and limits, auto upload and auto clear, mobile capture, native file system access, layout customization with presets and the default slot, themes, events, internationalization, and styling - UploadView: resume upload inside a job application form - UploadPickingFilesView: multi-file gallery uploader with filter switching - UploadAutoUploadView: ticket submission with background attachment uploads - UploadPresetsView: side-by-side comparison of the four chrome presets - UploadDefaultSlotView: HEADLESS preset with projected drop surface - UploadEventsView: progress bar and status line driven by onChange, onListProgress, and onComplete

github-actions · 2026-05-28T02:33:53Z

+layout.add(upload);
+```
+
+The example below drops a resume `Upload` into a job application form, alongside a name field and submit button.


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.WordList] Use 'app' instead of 'application'.

MatthewHawkins · 2026-05-28T15:12:40Z

@@ -0,0 +1,337 @@
+---


Please include a description at the top for llm.txt parsing:

description: This component...

MatthewHawkins · 2026-05-28T15:14:27Z

+- **`ON_DROP`** uploads as soon as files are dropped onto the component.
+- **`ALWAYS`** covers both paths.
+
+Auto upload pairs well with the `BUTTON_ONLY` or `INLINE` presets, where there's no Upload button for the user to click anyway. For workflows where the user needs to review the selection before sending, leave auto upload off.


This likely belongs in a tip, but I'll leave that up to your judgement!

MatthewHawkins · 2026-05-28T15:15:34Z

+
+When the user picks a new batch, auto clear decides what to do with the entries already in the list. Clearing happens at the moment of the next pick, not on upload completion, so finished uploads stay visible until the user picks again.
+
+:::warning Auto clear has subtle triggers


I'd recommend moving this after the ENUM options, but up to you

MatthewHawkins · 2026-05-28T15:17:11Z

+:::tip Capture and filters
+Restrict selection to image extensions so the camera opens in still mode, or to video extensions so it opens in recording mode. Without a corresponding filter, a capture mode falls back to the standard picker on most platforms. Desktop browsers ignore the capture setting entirely.
+:::
+


Totally up to you here, but I could see benefit in linking to the PWA section of the docs here for more info on using webforJ for mobile web app development

MatthewHawkins · 2026-05-28T15:19:29Z

+height='400px'
+/>
+
+## Themes {#themes}


I'd move this section to right before the end/styling section

laurenic0l · 2026-05-28T20:44:17Z

Thanks for the feedback @MatthewHawkins. I've applied the changes

hyyan

@laurenic0l Looking great overall, just a few more requests!

hyyan · 2026-05-29T08:55:31Z

@@ -0,0 +1,345 @@
+---
+title: Upload


add new-content badge

hyyan · 2026-05-29T08:55:58Z

@@ -0,0 +1,345 @@
+---
+title: Upload
+sidebar_position: 160


Add the component to the gallery

hyyan · 2026-05-29T09:03:57Z

+        submit);
+  }
+
+  private FlexLayout fieldGroup(String label, String helperText, Upload upload) {


The label is not aligned with the "full name" input's label horizontally

hyyan · 2026-05-29T09:06:15Z

+
+@Route
+@StyleSheet("ws://css/upload/upload.css")
+@FrameTitle("Upload Basic")


All upload demos should automatically delete any uploaded files directly from the server, and file system access must be disabled, as iframes block this feature otherwise the upload will never be triggered.

resume.setFileSystemAccess(false); resume.onUpload(e -> { e.getFiles().forEach(file -> { try { file.delete(); } catch (Exception ex) { // skip } }); });

hyyan · 2026-05-29T09:11:10Z

+@Route
+@StyleSheet("ws://css/upload/upload.css")
+@FrameTitle("Upload Basic")
+public class UploadView extends Composite<FlexLayout> {


Simplify this demo to only include the uploa, nothing else. The form is not functional.

hyyan · 2026-05-29T09:25:02Z

+upload.setAutoClear(Upload.AutoClear.ALL);
+```
+
+:::warning Auto clear has subtle triggers


It's not possible to select a file programmatically, so I'm not sure what that tip is referring to.

hyyan · 2026-05-29T09:32:26Z

+
+## Customizing the layout {#customizing-the-layout}
+
+The component is built from five visible parts: the picker button, the drop label, the file list, the upload button, and the cancel button. By default all five are visible, but the layout can be reshaped with presets for common picker shapes, or with per-part visibility controls for finer adjustments.


By default all five are visible, -> cancel button is not visible by default

hyyan · 2026-05-29T09:36:35Z

+@Route
+@StyleSheet("ws://css/upload/upload.css")
+@FrameTitle("Upload Default Slot")
+public class UploadDefaultSlotView extends Composite<FlexLayout> {


This demo doesn't do anything useful, please use the table demo instead.

hyyan · 2026-05-29T09:40:10Z

+```java
+upload.onProgress(e -> {
+    // Fires repeatedly during a single file's transfer.
+    int percent = (int) e.getProgress();


why casting to int ?

hyyan · 2026-05-29T09:46:50Z

+
+@Route
+@FrameTitle("Upload Themes")
+public class UploadThemesView extends Composite<FlexLayout> {


Only display the primary theme and use the inline preset.

laurenic0l added 3 commits May 27, 2026 22:07

fixes for accuracy

184c3c7

fix for accuracy

241dd91

github-actions Bot reviewed May 28, 2026

View reviewed changes

laurenic0l marked this pull request as ready for review May 28, 2026 02:34

laurenic0l requested review from EHandtkeBasis, MatthewHawkins, bbrennanbasis, gosteenBASIS and hyyan as code owners May 28, 2026 02:34

laurenic0l assigned hyyan and MatthewHawkins May 28, 2026

laurenic0l added the status: waiting-for-review The PR is ready. Waiting for team members to review. label May 28, 2026

hyyan added the status: needs-snapshot Update to the latest snapshot before this PR can be merged. label May 28, 2026

MatthewHawkins requested changes May 28, 2026

View reviewed changes

add themes demo and address review feedback

7cedb65

laurenic0l requested a review from MatthewHawkins May 28, 2026 20:43

hyyan requested changes May 29, 2026

View reviewed changes


		When the user picks a new batch, auto clear decides what to do with the entries already in the list. Clearing happens at the moment of the next pick, not on upload completion, so finished uploads stay visible until the user picks again.

		:::warning Auto clear has subtle triggers


		## Customizing the layout {#customizing-the-layout}

		The component is built from five visible parts: the picker button, the drop label, the file list, the upload button, and the cancel button. By default all five are visible, but the layout can be reshaped with presets for common picker shapes, or with per-part visibility controls for finer adjustments.

Conversation

laurenic0l commented May 28, 2026

Uh oh!

github-actions Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

laurenic0l commented May 28, 2026

Uh oh!

hyyan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants