Skip to content

Commit 4df202c

Browse files
totally-not-ai[bot]claudesissbruecker
authored
feat: add capture API to Upload and UploadButton (#10332)
**Review risk:** two-way door — additive API on Upload / UploadButton only; no existing behavior changes. ## Summary `<vaadin-upload>` and `<vaadin-upload-button>` both have a `capture` property that they pass to the hidden file input, but there was no Java API for it. Without it, opening the camera (or microphone) instead of the file browser on a mobile device needed `getElement().setProperty("capture", ...)`. ## What changed - New `UploadCapture` enum with `USER` (front-facing input) and `ENVIRONMENT` (back-facing input). - `Upload#setCapture(UploadCapture)` / `getCapture()`. - `UploadButton#setCapture(UploadCapture)` / `getCapture()`, for the modular `UploadManager` API, where the file input lives in the button. - `null` (the default) removes the property, so the file browser opens as before. It is only a browser hint: desktop browsers ignore it, and it does not restrict which files can be uploaded. ```java upload.setAcceptedMimeTypes("image/*"); upload.setCapture(UploadCapture.ENVIRONMENT); ``` ## Test summary - Unit tests for `Upload` and `UploadButton` cover the default value, both enum values, and clearing with `null`, checked through the element property. ## API Changes ### com.vaadin.flow.component.upload.UploadCapture ```java // Added public enum UploadCapture UploadCapture.USER UploadCapture.ENVIRONMENT ``` ### com.vaadin.flow.component.upload.Upload ```java // Added public UploadCapture getCapture() public void setCapture(UploadCapture capture) ``` ### com.vaadin.flow.component.upload.UploadButton ```java // Added public UploadCapture getCapture() public void setCapture(UploadCapture capture) ``` Fixes #10086 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: totally-not-ai[bot] <290682512+totally-not-ai[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Sascha Ißbrücker <sissbruecker@vaadin.com>
1 parent 8ea7555 commit 4df202c

5 files changed

Lines changed: 179 additions & 0 deletions

File tree

‎vaadin-upload-flow-parent/vaadin-upload-flow/src/main/java/com/vaadin/flow/component/upload/Upload.java‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -337,6 +337,46 @@ public boolean isDropAllowed() {
337337
return !getElement().getProperty("nodrop", false);
338338
}
339339

340+
/**
341+
* Gets the device input that is used for capturing a new file.
342+
*
343+
* @return the device input used for capturing a new file, or {@code null}
344+
* if not set
345+
* @see #setCapture(UploadCapture)
346+
* @since 25.4
347+
*/
348+
public UploadCapture getCapture() {
349+
return UploadCapture.fromValue(getElement().getProperty("capture"));
350+
}
351+
352+
/**
353+
* Sets the device input to use for capturing a new file, for example
354+
* {@link UploadCapture#ENVIRONMENT} to take a photo with the back camera of
355+
* a phone. On devices that support it, selecting files then opens the
356+
* camera or microphone directly instead of the file browser. The type of
357+
* input is determined by the accepted MIME types, for example
358+
* {@code "image/*"} for the camera, see
359+
* {@link #setAcceptedMimeTypes(String...)}.
360+
* <p>
361+
* This is only a hint to the browser. Devices without such an input, for
362+
* example desktop browsers, ignore it and open the file browser. It does
363+
* not restrict which files can be uploaded.
364+
* <p>
365+
* The default is {@code null}, which opens the file browser.
366+
*
367+
* @param capture
368+
* the device input to use for capturing a new file, or
369+
* {@code null} to choose existing files
370+
* @since 25.4
371+
*/
372+
public void setCapture(UploadCapture capture) {
373+
if (capture == null) {
374+
getElement().removeProperty("capture");
375+
} else {
376+
getElement().setProperty("capture", capture.getValue());
377+
}
378+
}
379+
340380
/**
341381
* Sets the accepted MIME types for uploads. Only files matching these MIME
342382
* types will be accepted. Wildcard patterns like {@code "image/*"} are

‎vaadin-upload-flow-parent/vaadin-upload-flow/src/main/java/com/vaadin/flow/component/upload/UploadButton.java‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,46 @@ private void doSetText(String text) {
8383
super.setText(text);
8484
}
8585

86+
/**
87+
* Gets the device input that is used for capturing a new file.
88+
*
89+
* @return the device input used for capturing a new file, or {@code null}
90+
* if not set
91+
* @see #setCapture(UploadCapture)
92+
* @since 25.4
93+
*/
94+
public UploadCapture getCapture() {
95+
return UploadCapture.fromValue(getElement().getProperty("capture"));
96+
}
97+
98+
/**
99+
* Sets the device input to use for capturing a new file, for example
100+
* {@link UploadCapture#ENVIRONMENT} to take a photo with the back camera of
101+
* a phone. On devices that support it, clicking the button then opens the
102+
* camera or microphone directly instead of the file browser. The type of
103+
* input is determined by the accepted MIME types of the manager, for
104+
* example {@code "image/*"} for the camera, see
105+
* {@link UploadManager#setAcceptedMimeTypes(String...)}.
106+
* <p>
107+
* This is only a hint to the browser. Devices without such an input, for
108+
* example desktop browsers, ignore it and open the file browser. It does
109+
* not restrict which files can be uploaded.
110+
* <p>
111+
* The default is {@code null}, which opens the file browser.
112+
*
113+
* @param capture
114+
* the device input to use for capturing a new file, or
115+
* {@code null} to choose existing files
116+
* @since 25.4
117+
*/
118+
public void setCapture(UploadCapture capture) {
119+
if (capture == null) {
120+
getElement().removeProperty("capture");
121+
} else {
122+
getElement().setProperty("capture", capture.getValue());
123+
}
124+
}
125+
86126
/**
87127
* Sets whether this button is enabled. When disabled, the button cannot be
88128
* used to select files.
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
/*
2+
* Copyright 2000-2026 Vaadin Ltd.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
5+
* use this file except in compliance with the License. You may obtain a copy of
6+
* the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12+
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13+
* License for the specific language governing permissions and limitations under
14+
* the License.
15+
*/
16+
package com.vaadin.flow.component.upload;
17+
18+
import java.util.Arrays;
19+
20+
/**
21+
* Specifies which device input to use for capturing a new file, for example a
22+
* photo with the camera, instead of choosing an existing file.
23+
*
24+
* @see Upload#setCapture(UploadCapture)
25+
* @see UploadButton#setCapture(UploadCapture)
26+
* @since 25.4
27+
*/
28+
public enum UploadCapture {
29+
/**
30+
* Use the user-facing device input, for example the front camera of a
31+
* phone.
32+
*/
33+
USER("user"),
34+
/**
35+
* Use the outward-facing device input, for example the back camera of a
36+
* phone.
37+
*/
38+
ENVIRONMENT("environment");
39+
40+
private final String value;
41+
42+
UploadCapture(String value) {
43+
this.value = value;
44+
}
45+
46+
String getValue() {
47+
return value;
48+
}
49+
50+
static UploadCapture fromValue(String value) {
51+
return Arrays.stream(values())
52+
.filter(capture -> capture.value.equals(value)).findFirst()
53+
.orElse(null);
54+
}
55+
}

‎vaadin-upload-flow-parent/vaadin-upload-flow/src/test/java/com/vaadin/flow/component/upload/tests/UploadButtonTest.java‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
import com.vaadin.flow.component.html.Div;
2727
import com.vaadin.flow.component.internal.PendingJavaScriptInvocation;
2828
import com.vaadin.flow.component.upload.UploadButton;
29+
import com.vaadin.flow.component.upload.UploadCapture;
2930
import com.vaadin.flow.component.upload.UploadManager;
3031
import com.vaadin.tests.MockUIExtension;
3132

@@ -143,4 +144,25 @@ void setUploadManager_changeManager_detachAndReattach_onlyOneManagerLinkJsExecut
143144
// Verify that the button is linked to manager2
144145
Assertions.assertSame(manager2, button.getUploadManager());
145146
}
147+
148+
@Test
149+
void capture() {
150+
UploadButton button = new UploadButton();
151+
Assertions.assertNull(button.getCapture());
152+
Assertions.assertFalse(button.getElement().hasProperty("capture"));
153+
154+
button.setCapture(UploadCapture.ENVIRONMENT);
155+
Assertions.assertEquals(UploadCapture.ENVIRONMENT, button.getCapture());
156+
Assertions.assertEquals("environment",
157+
button.getElement().getProperty("capture"));
158+
159+
button.setCapture(UploadCapture.USER);
160+
Assertions.assertEquals(UploadCapture.USER, button.getCapture());
161+
Assertions.assertEquals("user",
162+
button.getElement().getProperty("capture"));
163+
164+
button.setCapture(null);
165+
Assertions.assertNull(button.getCapture());
166+
Assertions.assertFalse(button.getElement().hasProperty("capture"));
167+
}
146168
}

‎vaadin-upload-flow-parent/vaadin-upload-flow/src/test/java/com/vaadin/flow/component/upload/tests/UploadTest.java‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
import com.vaadin.flow.component.HasEnabled;
2424
import com.vaadin.flow.component.shared.HasThemeVariant;
2525
import com.vaadin.flow.component.upload.Upload;
26+
import com.vaadin.flow.component.upload.UploadCapture;
2627
import com.vaadin.flow.component.upload.receivers.MemoryBuffer;
2728
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
2829

@@ -61,6 +62,27 @@ void implementsHasThemeVariant() {
6162
HasThemeVariant.class.isAssignableFrom(Upload.class));
6263
}
6364

65+
@Test
66+
void capture() {
67+
var upload = new Upload();
68+
Assertions.assertNull(upload.getCapture());
69+
Assertions.assertFalse(upload.getElement().hasProperty("capture"));
70+
71+
upload.setCapture(UploadCapture.ENVIRONMENT);
72+
Assertions.assertEquals(UploadCapture.ENVIRONMENT, upload.getCapture());
73+
Assertions.assertEquals("environment",
74+
upload.getElement().getProperty("capture"));
75+
76+
upload.setCapture(UploadCapture.USER);
77+
Assertions.assertEquals(UploadCapture.USER, upload.getCapture());
78+
Assertions.assertEquals("user",
79+
upload.getElement().getProperty("capture"));
80+
81+
upload.setCapture(null);
82+
Assertions.assertNull(upload.getCapture());
83+
Assertions.assertFalse(upload.getElement().hasProperty("capture"));
84+
}
85+
6486
// --- Accepted MIME Types ---
6587

6688
@Test

0 commit comments

Comments
 (0)