0
# Components
1

2
UI components for building Vaadin applications: inputs, displays, navigation, dialogs, and HTML elements.
3

4
**See also:** [Quick Component Reference](../index.md#quick-component-reference) in the main index for an alphabetical lookup table.
5

6
## Input Components
7

8
Form input components for collecting user data, including text fields, checkboxes, radio buttons, combo boxes, date pickers, and file uploads.
9

10
**Components in this section:** Button, TextField, TextArea, PasswordField, EmailField, NumberField, IntegerField, Checkbox, CheckboxGroup, RadioButtonGroup, ComboBox, MultiSelectComboBox, Select, DatePicker, TimePicker, DateTimePicker, Upload
11

12
### Button
13

14
```java { .api }
15
class Button extends Component {
16
    Button();
17
    Button(String text);
18
    Button(String text, ComponentEventListener<ClickEvent<Button>> listener);
19
    Button(Component icon);
20
    Button(Component icon, ComponentEventListener<ClickEvent<Button>> listener);
21
    void setText(String text);
22
    void setIcon(Component icon);
23
    void setIconAfterText(boolean iconAfterText);
24
    void setAutofocus(boolean autofocus);
25
    void setDisableOnClick(boolean disableOnClick);
26
    void addThemeVariants(ButtonVariant... variants);
27
    void removeThemeVariants(ButtonVariant... variants);
28
    Registration addClickListener(ComponentEventListener<ClickEvent<Button>> listener);
29
}
30

31
enum ButtonVariant implements ThemeVariant {
32
    LUMO_PRIMARY, LUMO_SECONDARY, LUMO_TERTIARY,
33
    LUMO_SUCCESS, LUMO_ERROR, LUMO_CONTRAST,
34
    LUMO_SMALL, LUMO_LARGE, LUMO_ICON
35
}
36
```
37

38
### TextField
39

40
```java { .api }
41
class TextField extends Component implements HasValue<TextField, String> {
42
    TextField();
43
    TextField(String label);
44
    TextField(String label, String placeholder);
45
    TextField(String label, String initialValue, String placeholder);
46
    void setLabel(String label);
47
    void setPlaceholder(String placeholder);
48
    void setValue(String value);
49
    String getValue();
50
    void setClearButtonVisible(boolean clearButtonVisible);
51
    void setRequired(boolean required);
52
    void setRequiredIndicatorVisible(boolean requiredIndicatorVisible);
53
    void setValueChangeMode(ValueChangeMode mode);
54
    void setValueChangeTimeout(int valueChangeTimeout);
55
    void setMaxLength(int maxLength);
56
    void setMinLength(int minLength);
57
    void setPattern(String pattern);
58
    void setErrorMessage(String errorMessage);
59
    void setHelperText(String helperText);
60
    void setPrefixComponent(Component component);
61
    void setSuffixComponent(Component component);
62
    Registration addValueChangeListener(ValueChangeListener<? super ComponentValueChangeEvent<TextField, String>> listener);
63
}
64
```
65

66
### TextArea
67

68
```java { .api }
69
class TextArea extends Component implements HasValue<TextArea, String> {
70
    TextArea();
71
    TextArea(String label);
72
    TextArea(String label, String placeholder);
73
    void setLabel(String label);
74
    void setPlaceholder(String placeholder);
75
    void setValue(String value);
76
    String getValue();
77
    void setMaxLength(int maxLength);
78
    void setMinLength(int minLength);
79
    void setHeight(String height);
80
    Registration addValueChangeListener(ValueChangeListener<? super ComponentValueChangeEvent<TextArea, String>> listener);
81
}
82
```
83

84
### Specialized Text Fields
85

86
```java { .api }
87
class PasswordField extends Component implements HasValue<PasswordField, String> {
88
    PasswordField();
89
    PasswordField(String label);
90
    void setLabel(String label);
91
    void setRevealButtonVisible(boolean revealButtonVisible);
92
}
93

94
class EmailField extends Component implements HasValue<EmailField, String> {
95
    EmailField();
96
    EmailField(String label);
97
    void setPattern(String pattern);
98
}
99

100
class NumberField extends Component implements HasValue<NumberField, Double> {
101
    NumberField();
102
    NumberField(String label);
103
    void setMin(double min);
104
    void setMax(double max);
105
    void setStep(double step);
106
    void setHasControls(boolean hasControls);
107
}
108

109
class IntegerField extends Component implements HasValue<IntegerField, Integer> {
110
    IntegerField();
111
    IntegerField(String label);
112
    void setMin(int min);
113
    void setMax(int max);
114
    void setStep(int step);
115
    void setHasControls(boolean hasControls);
116
}
117
```
118

119
### Checkbox
120

121
```java { .api }
122
class Checkbox extends Component implements HasValue<Checkbox, Boolean> {
123
    Checkbox();
124
    Checkbox(String label);
125
    Checkbox(String label, boolean initialValue);
126
    void setLabel(String label);
127
    void setValue(Boolean value);
128
    Boolean getValue();
129
    void setIndeterminate(boolean indeterminate);
130
    Registration addValueChangeListener(ValueChangeListener<? super ComponentValueChangeEvent<Checkbox, Boolean>> listener);
131
}
132

133
class CheckboxGroup<T> extends Component implements HasValue<CheckboxGroup<T>, Set<T>> {
134
    CheckboxGroup();
135
    CheckboxGroup(String label);
136
    void setLabel(String label);
137
    void setItems(Collection<T> items);
138
    void setItems(T... items);
139
    void setItemLabelGenerator(ItemLabelGenerator<T> itemLabelGenerator);
140
    void setValue(Set<T> value);
141
    Set<T> getValue();
142
}
143
```
144

145
### RadioButtonGroup
146

147
```java { .api }
148
class RadioButtonGroup<T> extends Component implements HasValue<RadioButtonGroup<T>, T> {
149
    RadioButtonGroup();
150
    RadioButtonGroup(String label);
151
    void setLabel(String label);
152
    void setItems(Collection<T> items);
153
    void setItems(T... items);
154
    void setItemLabelGenerator(ItemLabelGenerator<T> itemLabelGenerator);
155
    void setValue(T value);
156
    T getValue();
157
}
158
```
159

160
### ComboBox and Select
161

162
```java { .api }
163
class ComboBox<T> extends Component implements HasValue<ComboBox<T>, T> {
164
    ComboBox();
165
    ComboBox(String label);
166
    void setLabel(String label);
167
    void setItems(Collection<T> items);
168
    void setItems(T... items);
169
    void setItemLabelGenerator(ItemLabelGenerator<T> generator);
170
    void setDataProvider(DataProvider<T, String> dataProvider);
171
    void setValue(T value);
172
    T getValue();
173
    void setAllowCustomValue(boolean allowCustomValue);
174
    void setClearButtonVisible(boolean clearButtonVisible);
175
    void setPlaceholder(String placeholder);
176
    Registration addValueChangeListener(ValueChangeListener<? super ComponentValueChangeEvent<ComboBox<T>, T>> listener);
177
    Registration addCustomValueSetListener(ComponentEventListener<CustomValueSetEvent<ComboBox<T>>> listener);
178
}
179

180
class MultiSelectComboBox<T> extends Component implements HasValue<MultiSelectComboBox<T>, Set<T>> {
181
    MultiSelectComboBox();
182
    MultiSelectComboBox(String label);
183
    void setItems(Collection<T> items);
184
    void setValue(Set<T> value);
185
    Set<T> getValue();
186
}
187

188
class Select<T> extends Component implements HasValue<Select<T>, T> {
189
    Select();
190
    Select(String label);
191
    void setLabel(String label);
192
    void setItems(Collection<T> items);
193
    void setItems(T... items);
194
    void setItemLabelGenerator(ItemLabelGenerator<T> generator);
195
    void setValue(T value);
196
    T getValue();
197
    void setPlaceholder(String placeholder);
198
}
199
```
200

201
### Date and Time Pickers
202

203
```java { .api }
204
class DatePicker extends Component implements HasValue<DatePicker, LocalDate> {
205
    DatePicker();
206
    DatePicker(String label);
207
    DatePicker(String label, LocalDate initialDate);
208
    void setLabel(String label);
209
    void setValue(LocalDate value);
210
    LocalDate getValue();
211
    void setMin(LocalDate min);
212
    void setMax(LocalDate max);
213
    void setPlaceholder(String placeholder);
214
    void setWeekNumbersVisible(boolean weekNumbersVisible);
215
}
216

217
class TimePicker extends Component implements HasValue<TimePicker, LocalTime> {
218
    TimePicker();
219
    TimePicker(String label);
220
    void setLabel(String label);
221
    void setValue(LocalTime value);
222
    LocalTime getValue();
223
    void setMin(LocalTime min);
224
    void setMax(LocalTime max);
225
    void setStep(Duration step);
226
}
227

228
class DateTimePicker extends Component implements HasValue<DateTimePicker, LocalDateTime> {
229
    DateTimePicker();
230
    DateTimePicker(String label);
231
    void setLabel(String label);
232
    void setValue(LocalDateTime value);
233
    LocalDateTime getValue();
234
    void setDatePlaceholder(String placeholder);
235
    void setTimePlaceholder(String placeholder);
236
}
237
```
238

239
### Upload
240

241
```java { .api }
242
class Upload extends Component {
243
    Upload();
244
    Upload(Receiver receiver);
245
    void setReceiver(Receiver receiver);
246
    void setAcceptedFileTypes(String... acceptedFileTypes);
247
    void setMaxFiles(int maxFiles);
248
    void setMaxFileSize(int maxFileSize);
249
    void setDropLabel(String dropLabel);
250
    void setUploadButton(Component uploadButton);
251
    Registration addSucceededListener(ComponentEventListener<SucceededEvent> listener);
252
    Registration addFailedListener(ComponentEventListener<FailedEvent> listener);
253
    Registration addFileRejectedListener(ComponentEventListener<FileRejectedEvent> listener);
254
}
255

256
interface Receiver {
257
    OutputStream receiveUpload(String filename, String mimeType);
258
}
259

260
class MemoryBuffer implements Receiver {
261
    MemoryBuffer();
262
    OutputStream receiveUpload(String filename, String mimeType);
263
    InputStream getInputStream();
264
    String getFileName();
265
}
266
```
267

268
**Examples:**
269

270
```java
271
Button save = new Button("Save", e -> Notification.show("Saved!"));
272
save.addThemeVariants(ButtonVariant.LUMO_PRIMARY);
273

274
TextField name = new TextField("Name");
275
name.setRequired(true);
276
name.setValueChangeMode(ValueChangeMode.EAGER);
277

278
ComboBox<String> country = new ComboBox<>("Country");
279
country.setItems("USA", "UK", "Canada");
280

281
DatePicker date = new DatePicker("Birth Date");
282
date.setMax(LocalDate.now());
283

284
MemoryBuffer buffer = new MemoryBuffer();
285
Upload upload = new Upload(buffer);
286
upload.setAcceptedFileTypes("image/*");
287
upload.addSucceededListener(e -> {
288
    InputStream is = buffer.getInputStream();
289
    // Process file
290
});
291
```
292

293
## Display Components
294

295
**Components in this section:** Grid, ProgressBar, Avatar, Icon
296

297
**Related:** For data binding with Grid, see [Data Integration](../data-integration.md).
298

299
```java { .api }
300
class Grid<T> extends Component {
301
    Grid();
302
    Grid(Class<T> beanType);
303
    Column<T> addColumn(ValueProvider<T, ?> valueProvider);
304
    Column<T> addColumn(String propertyName);
305
    void setColumns(String... propertyNames);
306
    void setItems(Collection<T> items);
307
    void setDataProvider(DataProvider<T, ?> dataProvider);
308
    void setSelectionMode(SelectionMode mode);
309
    Registration addSelectionListener(SelectionListener<Grid<T>, T> listener);
310
}
311

312
interface Grid.Column<T> {
313
    Column<T> setHeader(String header);
314
    Column<T> setSortable(boolean sortable);
315
    Column<T> setAutoWidth(boolean autoWidth);
316
    Column<T> setWidth(String width);
317
}
318

319
class ProgressBar extends Component {
320
    ProgressBar();
321
    ProgressBar(double min, double max);
322
    void setValue(double value);
323
    void setIndeterminate(boolean indeterminate);
324
}
325

326
class Avatar extends Component {
327
    Avatar();
328
    Avatar(String name);
329
    void setName(String name);
330
    void setImage(String url);
331
    void addThemeVariants(AvatarVariant... variants);
332
}
333

334
class Icon extends Component {
335
    Icon(VaadinIcon icon);
336
    void setColor(String color);
337
    void setSize(String size);
338
}
339
```
340

341
**Examples:**
342

343
```java
344
Grid<Person> grid = new Grid<>(Person.class);
345
grid.setColumns("name", "email", "age");
346
grid.setItems(people);
347
grid.addSelectionListener(e -> e.getFirstSelectedItem()
348
    .ifPresent(p -> Notification.show("Selected: " + p.getName())));
349

350
Grid<Product> products = new Grid<>();
351
products.addColumn(Product::getName).setHeader("Name");
352
products.addColumn(p -> "$" + p.getPrice()).setHeader("Price");
353
products.setDataProvider(DataProvider.fromCallbacks(
354
    q -> productService.fetch(q.getOffset(), q.getLimit()).stream(),
355
    q -> productService.count()
356
));
357
```
358

359
## Navigation Components
360

361
**Components in this section:** Tabs, Tab, TabSheet, MenuBar, MenuItem, SideNav, SideNavItem
362

363
**Related:** For routing navigation, see [Core Framework](../core-framework.md#routing).
364

365
```java { .api }
366
class Tabs extends Component {
367
    Tabs();
368
    Tabs(Tab... tabs);
369
    void add(Tab... tabs);
370
    void setSelectedTab(Tab tab);
371
    Tab getSelectedTab();
372
    Registration addSelectedChangeListener(ComponentEventListener<SelectedChangeEvent> listener);
373
}
374

375
class Tab extends Component {
376
    Tab();
377
    Tab(String label);
378
    void setLabel(String label);
379
}
380

381
class TabSheet extends Component {
382
    TabSheet();
383
    Tab add(String label, Component content);
384
    void setSelectedTab(Tab tab);
385
}
386

387
class MenuBar extends Component {
388
    MenuBar();
389
    MenuItem addItem(String text);
390
    MenuItem addItem(String text, ComponentEventListener<ClickEvent<MenuItem>> listener);
391
}
392

393
interface MenuItem {
394
    SubMenu getSubMenu();
395
    void setText(String text);
396
}
397

398
class SideNav extends Component {
399
    SideNav();
400
    void addItem(SideNavItem item);
401
}
402

403
class SideNavItem extends Component {
404
    SideNavItem(String label);
405
    SideNavItem(String label, Class<? extends Component> navigationTarget);
406
    void addItem(SideNavItem item);
407
}
408
```
409

410
**Examples:**
411

412
```java
413
Tabs tabs = new Tabs();
414
tabs.add(new Tab("Home"), new Tab("Profile"), new Tab("Settings"));
415
tabs.addSelectedChangeListener(e -> handleTabChange(e.getSelectedTab()));
416

417
TabSheet tabSheet = new TabSheet();
418
tabSheet.add("Overview", overviewLayout);
419
tabSheet.add("Details", detailsLayout);
420

421
SideNav nav = new SideNav();
422
nav.addItem(new SideNavItem("Dashboard", DashboardView.class));
423
nav.addItem(new SideNavItem("Products", ProductsView.class));
424
```
425

426
## Dialogs & Overlays
427

428
**Components in this section:** Dialog, ConfirmDialog, Notification
429

430
```java { .api }
431
class Dialog extends Component {
432
    Dialog();
433
    void add(Component... components);
434
    void open();
435
    void close();
436
    void setModal(boolean modal);
437
    void setHeaderTitle(String title);
438
    Registration addOpenedChangeListener(ComponentEventListener<OpenedChangeEvent<Dialog>> listener);
439
}
440

441
class ConfirmDialog extends Component {
442
    ConfirmDialog();
443
    ConfirmDialog(String header, String text, String confirmText,
444
                  ComponentEventListener<ConfirmEvent> confirmListener);
445
    void setHeader(String header);
446
    void setText(String text);
447
    void open();
448
}
449

450
class Notification extends Component {
451
    Notification();
452
    Notification(String text);
453
    Notification(String text, int duration, Position position);
454
    void setPosition(Position position);
455
    static Notification show(String text);
456
    static Notification show(String text, int duration, Position position);
457
}
458

459
enum Notification.Position {
460
    TOP_START, TOP_CENTER, TOP_END,
461
    MIDDLE,
462
    BOTTOM_START, BOTTOM_CENTER, BOTTOM_END
463
}
464
```
465

466
**Examples:**
467

468
```java
469
Dialog dialog = new Dialog();
470
dialog.setHeaderTitle("Confirmation");
471
dialog.add(new Paragraph("Are you sure?"));
472
dialog.getFooter().add(
473
    new Button("Cancel", e -> dialog.close()),
474
    new Button("OK", e -> { /* handle */ dialog.close(); })
475
);
476
dialog.open();
477

478
ConfirmDialog confirm = new ConfirmDialog("Delete Item",
479
    "Are you sure?", "Delete",
480
    e -> Notification.show("Deleted"),
481
    "Cancel", e -> {});
482
confirm.open();
483

484
Notification.show("Success!", 3000, Notification.Position.TOP_CENTER);
485
```
486

487
## HTML Components
488

489
**Components in this section:** Div, Span, H1-H6, Paragraph, Anchor, Image
490

491
**Note:** These are Java wrappers for standard HTML elements. For more HTML elements, see the [Vaadin HTML Components API](https://vaadin.com/docs/latest/components/html-elements).
492

493
```java { .api }
494
class Div extends HtmlContainer {
495
    Div();
496
    Div(Component... components);
497
}
498

499
class Span extends HtmlContainer {
500
    Span();
501
    Span(String text);
502
}
503

504
class H1 extends HtmlComponent {
505
    H1();
506
    H1(String text);
507
}
508
// H2, H3, H4, H5, H6 follow same pattern
509

510
class Paragraph extends HtmlComponent {
511
    Paragraph();
512
    Paragraph(String text);
513
}
514

515
class Anchor extends HtmlComponent {
516
    Anchor();
517
    Anchor(String href, String text);
518
    void setHref(String href);
519
}
520

521
class Image extends HtmlComponent {
522
    Image();
523
    Image(String src, String alt);
524
    void setSrc(String src);
525
}
526
```
527

528
**Examples:**
529

530
```java
531
Div container = new Div();
532
container.add(new H1("Title"), new Paragraph("Content"));
533

534
Anchor link = new Anchor("https://vaadin.com", "Visit Vaadin");
535
Image logo = new Image("images/logo.png", "Logo");
536
```
537