0
# Core Framework
1

2
The Vaadin Flow framework provides the foundation for building web applications, including routing, component lifecycle, server configuration, and frontend integration.
3

4
**Quick links:** [Component Base Classes](#component-base-classes) | [Routing](#routing) | [Server Configuration](#server-and-configuration) | [Page Interaction](#page-and-browser-interaction) | [Frontend Integration](#frontend-integration)
5

6
## Component Base Classes
7

8
Core classes that all Vaadin components extend from.
9

10
```java { .api }
11
/**
12
 * Base class for all Vaadin UI components.
13
 * Provides common functionality for visibility, styling, element access, and UI access.
14
 */
15
abstract class Component {
16
    /**
17
     * Sets the component's id attribute
18
     * @param id - Component identifier
19
     */
20
    void setId(String id);
21

22
    /**
23
     * Gets the component's id
24
     * @return Optional containing id if set
25
     */
26
    Optional<String> getId();
27

28
    /**
29
     * Sets whether component is visible
30
     * @param visible - true to show, false to hide
31
     */
32
    void setVisible(boolean visible);
33

34
    /**
35
     * Checks if component is visible
36
     * @return true if visible
37
     */
38
    boolean isVisible();
39

40
    /**
41
     * Adds CSS class name to component
42
     * @param className - CSS class name
43
     */
44
    void addClassName(String className);
45

46
    /**
47
     * Removes CSS class name from component
48
     * @param className - CSS class name to remove
49
     */
50
    void removeClassName(String className);
51

52
    /**
53
     * Sets CSS class names, replacing previous classes
54
     * @param className - CSS class name(s)
55
     */
56
    void setClassName(String className);
57

58
    /**
59
     * Gets underlying DOM element
60
     * @return Element instance
61
     */
62
    Element getElement();
63

64
    /**
65
     * Gets UI instance this component belongs to
66
     * @return Optional containing UI if attached
67
     */
68
    Optional<UI> getUI();
69

70
    /**
71
     * Adds listener for attach events
72
     * @param listener - Attach event listener
73
     * @return Registration for removing listener
74
     */
75
    Registration addAttachListener(ComponentEventListener<AttachEvent> listener);
76

77
    /**
78
     * Adds listener for detach events
79
     * @param listener - Detach event listener
80
     * @return Registration for removing listener
81
     */
82
    Registration addDetachListener(ComponentEventListener<DetachEvent> listener);
83
}
84

85
/**
86
 * Base class for custom composite components
87
 */
88
abstract class Composite<T extends Component> extends Component {
89
    /**
90
     * Gets the composed content component
91
     * @return Content component
92
     */
93
    protected abstract T initContent();
94

95
    /**
96
     * Gets the content component
97
     * @return Content component instance
98
     */
99
    protected T getContent();
100
}
101

102
/**
103
 * Interface for components that can contain other components
104
 */
105
interface HasComponents {
106
    /**
107
     * Adds components to this container
108
     * @param components - Components to add
109
     */
110
    void add(Component... components);
111

112
    /**
113
     * Removes components from this container
114
     * @param components - Components to remove
115
     */
116
    void remove(Component... components);
117

118
    /**
119
     * Removes all components from this container
120
     */
121
    void removeAll();
122

123
    /**
124
     * Adds component at specific index
125
     * @param index - Index position
126
     * @param component - Component to add
127
     */
128
    void addComponentAtIndex(int index, Component component);
129
}
130

131
/**
132
 * Interface for components with styling capabilities
133
 */
134
interface HasStyle {
135
    /**
136
     * Adds CSS class name(s)
137
     * @param className - CSS class name(s)
138
     */
139
    void addClassName(String className);
140

141
    /**
142
     * Removes CSS class name(s)
143
     * @param className - CSS class name(s)
144
     */
145
    void removeClassName(String className);
146

147
    /**
148
     * Sets CSS class name(s), replacing previous
149
     * @param className - CSS class name(s)
150
     */
151
    void setClassName(String className);
152

153
    /**
154
     * Gets style object for inline styles
155
     * @return Style instance
156
     */
157
    Style getStyle();
158
}
159

160
/**
161
 * Interface for components with size configuration
162
 */
163
interface HasSize {
164
    /**
165
     * Sets width
166
     * @param width - Width value with unit (e.g., "200px", "50%")
167
     */
168
    void setWidth(String width);
169

170
    /**
171
     * Sets height
172
     * @param height - Height value with unit
173
     */
174
    void setHeight(String height);
175

176
    /**
177
     * Sets min width
178
     * @param minWidth - Minimum width value with unit
179
     */
180
    void setMinWidth(String minWidth);
181

182
    /**
183
     * Sets max width
184
     * @param maxWidth - Maximum width value with unit
185
     */
186
    void setMaxWidth(String maxWidth);
187

188
    /**
189
     * Sets width to 100%
190
     */
191
    void setWidthFull();
192

193
    /**
194
     * Sets height to 100%
195
     */
196
    void setHeightFull();
197

198
    /**
199
     * Sets both width and height to 100%
200
     */
201
    void setSizeFull();
202
}
203

204
/**
205
 * Interface for components that can be enabled/disabled
206
 */
207
interface HasEnabled {
208
    /**
209
     * Sets whether component is enabled
210
     * @param enabled - true to enable, false to disable
211
     */
212
    void setEnabled(boolean enabled);
213

214
    /**
215
     * Checks if component is enabled
216
     * @return true if enabled
217
     */
218
    boolean isEnabled();
219
}
220

221
/**
222
 * Interface for input components with values
223
 */
224
interface HasValue<E extends HasValueChangeEvent<V>, V> extends HasEnabled {
225
    /**
226
     * Sets the value
227
     * @param value - New value
228
     */
229
    void setValue(V value);
230

231
    /**
232
     * Gets the current value
233
     * @return Current value
234
     */
235
    V getValue();
236

237
    /**
238
     * Adds value change listener
239
     * @param listener - Value change listener
240
     * @return Registration for removing listener
241
     */
242
    Registration addValueChangeListener(ValueChangeListener<? super E> listener);
243

244
    /**
245
     * Sets whether component is read-only
246
     * @param readOnly - true for read-only
247
     */
248
    void setReadOnly(boolean readOnly);
249

250
    /**
251
     * Checks if component is read-only
252
     * @return true if read-only
253
     */
254
    boolean isReadOnly();
255

256
    /**
257
     * Sets whether component is required
258
     * @param required - true if required
259
     */
260
    void setRequiredIndicatorVisible(boolean required);
261
}
262
```
263

264
## Routing
265

266
Declarative and programmatic routing system for navigation.
267

268
```java { .api }
269
/**
270
 * Annotation to mark a class as a routable view
271
 */
272
@Target(ElementType.TYPE)
273
@Retention(RetentionPolicy.RUNTIME)
274
@interface Route {
275
    /**
276
     * URL path for this route
277
     * @return URL path (empty string for root)
278
     */
279
    String value() default "";
280

281
    /**
282
     * Parent layout class
283
     * @return Layout class
284
     */
285
    Class<? extends RouterLayout> layout() default UI.class;
286
}
287

288
/**
289
 * Annotation to set page title
290
 */
291
@Target(ElementType.TYPE)
292
@Retention(RetentionPolicy.RUNTIME)
293
@interface PageTitle {
294
    /**
295
     * Page title text
296
     * @return Title string
297
     */
298
    String value();
299
}
300

301
/**
302
 * Annotation for route prefix on layouts
303
 */
304
@Target(ElementType.TYPE)
305
@Retention(RetentionPolicy.RUNTIME)
306
@interface RoutePrefix {
307
    /**
308
     * URL prefix for all child routes
309
     * @return URL prefix
310
     */
311
    String value();
312
}
313

314
/**
315
 * Annotation for menu integration (Vaadin 24+)
316
 */
317
@Target(ElementType.TYPE)
318
@Retention(RetentionPolicy.RUNTIME)
319
@interface Menu {
320
    /**
321
     * Menu item title
322
     * @return Menu title
323
     */
324
    String title() default "";
325

326
    /**
327
     * Menu item order
328
     * @return Order value (lower values first)
329
     */
330
    double order() default Integer.MAX_VALUE;
331
}
332

333
/**
334
 * Component for navigation links
335
 */
336
class RouterLink extends Component {
337
    /**
338
     * Creates router link
339
     */
340
    RouterLink();
341

342
    /**
343
     * Creates router link with text and target
344
     * @param text - Link text
345
     * @param navigationTarget - Target view class
346
     */
347
    RouterLink(String text, Class<? extends Component> navigationTarget);
348

349
    /**
350
     * Sets link text
351
     * @param text - Link text
352
     */
353
    void setText(String text);
354

355
    /**
356
     * Sets navigation target
357
     * @param navigationTarget - Target view class
358
     */
359
    void setRoute(Class<? extends Component> navigationTarget);
360
}
361

362
/**
363
 * Interface for route enter lifecycle
364
 */
365
interface BeforeEnterObserver {
366
    /**
367
     * Called before entering a route
368
     * @param event - Before enter event
369
     */
370
    void beforeEnter(BeforeEnterEvent event);
371
}
372

373
/**
374
 * Event fired before entering a route
375
 */
376
class BeforeEnterEvent {
377
    /**
378
     * Gets navigation location
379
     * @return Location instance
380
     */
381
    Location getLocation();
382

383
    /**
384
     * Reroutes to different view
385
     * @param navigationTarget - Target view class
386
     */
387
    void rerouteTo(Class<? extends Component> navigationTarget);
388

389
    /**
390
     * Forwards to error view
391
     * @param exception - Exception to display
392
     */
393
    void rerouteToError(Exception exception);
394
}
395

396
/**
397
 * Interface for route leave lifecycle
398
 */
399
interface BeforeLeaveObserver {
400
    /**
401
     * Called before leaving a route
402
     * @param event - Before leave event
403
     */
404
    void beforeLeave(BeforeLeaveEvent event);
405
}
406

407
/**
408
 * Event fired before leaving a route
409
 */
410
class BeforeLeaveEvent {
411
    /**
412
     * Postpones navigation
413
     * @return ContinueNavigationAction for resuming
414
     */
415
    ContinueNavigationAction postpone();
416
}
417

418
/**
419
 * Interface for routes with URL parameters
420
 */
421
interface HasUrlParameter<T> {
422
    /**
423
     * Sets parameters from URL
424
     * @param event - Before enter event
425
     * @param parameter - URL parameter
426
     */
427
    void setParameter(BeforeEvent event, T parameter);
428
}
429

430
/**
431
 * Utility for query parameters
432
 */
433
class QueryParameters {
434
    /**
435
     * Gets query parameters from map
436
     * @param parameters - Parameter map
437
     * @return QueryParameters instance
438
     */
439
    static QueryParameters simple(Map<String, String> parameters);
440

441
    /**
442
     * Gets parameter values
443
     * @param name - Parameter name
444
     * @return List of values
445
     */
446
    List<String> getParameters(String name);
447
}
448

449
/**
450
 * Main UI class
451
 */
452
class UI extends Component {
453
    /**
454
     * Gets current UI instance
455
     * @return Optional containing current UI
456
     */
457
    static Optional<UI> getCurrent();
458

459
    /**
460
     * Navigates to view
461
     * @param navigationTarget - Target view class
462
     */
463
    void navigate(Class<? extends Component> navigationTarget);
464

465
    /**
466
     * Navigates to view with parameters
467
     * @param navigationTarget - Target view class
468
     * @param parameter - URL parameter
469
     */
470
    <T> void navigate(Class<? extends Component> navigationTarget, T parameter);
471

472
    /**
473
     * Navigates to URL
474
     * @param url - URL string
475
     */
476
    void navigate(String url);
477

478
    /**
479
     * Gets page object
480
     * @return Page instance
481
     */
482
    Page getPage();
483
}
484
```
485

486
**Examples:**
487

488
```java
489
// Basic view with routing
490
@Route("dashboard")
491
@PageTitle("Dashboard")
492
public class DashboardView extends VerticalLayout {
493
    public DashboardView() {
494
        add(new H1("Dashboard"));
495
        // Add components
496
    }
497
}
498

499
// Navigation with RouterLink
500
VerticalLayout menu = new VerticalLayout();
501
menu.add(
502
    new RouterLink("Home", HomeView.class),
503
    new RouterLink("Products", ProductsView.class),
504
    new RouterLink("About", AboutView.class)
505
);
506

507
// Programmatic navigation
508
Button goToDetails = new Button("View Details", event -> {
509
    UI.getCurrent().navigate(DetailsView.class);
510
});
511

512
// With parameters
513
Button goToProduct = new Button("View Product", event -> {
514
    UI.getCurrent().navigate(ProductView.class, productId);
515
});
516

517
// Route lifecycle hooks
518
@Route("editor")
519
public class EditorView extends VerticalLayout
520
        implements BeforeLeaveObserver {
521

522
    @Override
523
    public void beforeLeave(BeforeLeaveEvent event) {
524
        if (hasUnsavedChanges()) {
525
            event.postpone();
526
            ConfirmDialog dialog = new ConfirmDialog(
527
                "Unsaved Changes",
528
                "Do you want to discard changes?",
529
                "Discard",
530
                confirmEvent -> event.getContinueNavigationAction().proceed(),
531
                "Cancel",
532
                cancelEvent -> {}
533
            );
534
            dialog.open();
535
        }
536
    }
537
}
538

539
// Custom composite component
540
public class UserCard extends Composite<Div> {
541
    private final Avatar avatar = new Avatar();
542
    private final Span name = new Span();
543
    private final Span email = new Span();
544

545
    @Override
546
    protected Div initContent() {
547
        Div card = new Div();
548
        card.addClassName("user-card");
549
        card.add(avatar, name, email);
550
        return card;
551
    }
552

553
    public void setUser(User user) {
554
        avatar.setName(user.getName());
555
        name.setText(user.getName());
556
        email.setText(user.getEmail());
557
    }
558
}
559
```
560

561
## Server and Configuration
562

563
Server-side configuration and application lifecycle.
564

565
```java { .api }
566
/**
567
 * Main Vaadin servlet
568
 */
569
class VaadinServlet extends HttpServlet {
570
    /**
571
     * Creates Vaadin servlet
572
     */
573
    VaadinServlet();
574
}
575

576
/**
577
 * Vaadin service singleton
578
 */
579
class VaadinService {
580
    /**
581
     * Gets current service instance
582
     * @return Current VaadinService
583
     */
584
    static VaadinService getCurrent();
585
}
586

587
/**
588
 * User session
589
 */
590
class VaadinSession {
591
    /**
592
     * Gets current session
593
     * @return Optional containing current session
594
     */
595
    static Optional<VaadinSession> getCurrent();
596

597
    /**
598
     * Sets session attribute
599
     * @param name - Attribute name
600
     * @param value - Attribute value
601
     */
602
    void setAttribute(String name, Object value);
603

604
    /**
605
     * Gets session attribute
606
     * @param name - Attribute name
607
     * @return Attribute value
608
     */
609
    Object getAttribute(String name);
610
}
611

612
/**
613
 * Annotation for Progressive Web App configuration
614
 */
615
@Target(ElementType.TYPE)
616
@Retention(RetentionPolicy.RUNTIME)
617
@interface PWA {
618
    /**
619
     * Application name
620
     * @return App name
621
     */
622
    String name();
623

624
    /**
625
     * Short application name
626
     * @return Short name
627
     */
628
    String shortName() default "";
629

630
    /**
631
     * App description
632
     * @return Description
633
     */
634
    String description() default "";
635
}
636

637
/**
638
 * Interface for application shell configuration
639
 */
640
interface AppShellConfigurator {
641
}
642

643
/**
644
 * Annotation for server push configuration
645
 */
646
@Target(ElementType.TYPE)
647
@Retention(RetentionPolicy.RUNTIME)
648
@interface Push {
649
    /**
650
     * Push mode
651
     * @return PushMode enum value
652
     */
653
    PushMode value() default PushMode.AUTOMATIC;
654
}
655

656
enum PushMode {
657
    DISABLED, MANUAL, AUTOMATIC
658
}
659

660
/**
661
 * Annotation for theme selection
662
 */
663
@Target(ElementType.TYPE)
664
@Retention(RetentionPolicy.RUNTIME)
665
@interface Theme {
666
    /**
667
     * Theme name or class
668
     * @return Theme identifier
669
     */
670
    String value() default "";
671

672
    /**
673
     * Theme variant (e.g., "dark")
674
     * @return Variant name
675
     */
676
    String variant() default "";
677
}
678
```
679

680
**Examples:**
681

682
```java
683
// Progressive Web App configuration
684
import com.vaadin.flow.component.page.AppShellConfigurator;
685
import com.vaadin.flow.server.PWA;
686
import com.vaadin.flow.theme.Theme;
687
import com.vaadin.flow.theme.lumo.Lumo;
688

689
@Theme(value = Lumo.class)
690
@PWA(
691
    name = "My Application",
692
    shortName = "MyApp",
693
    description = "My awesome Vaadin application"
694
)
695
public class AppShell implements AppShellConfigurator {
696
}
697

698
// Session attributes
699
VaadinSession.getCurrent().ifPresent(session -> {
700
    session.setAttribute("userId", user.getId());
701
    Object userId = session.getAttribute("userId");
702
});
703
```
704

705
## Page and Browser Interaction
706

707
Interaction with browser page and JavaScript execution.
708

709
```java { .api }
710
/**
711
 * Represents the browser page
712
 */
713
class Page {
714
    /**
715
     * Executes JavaScript in browser
716
     * @param expression - JavaScript expression
717
     * @return PendingJavaScriptResult for handling result
718
     */
719
    PendingJavaScriptResult executeJs(String expression, Serializable... parameters);
720

721
    /**
722
     * Sets page title
723
     * @param title - Page title
724
     */
725
    void setTitle(String title);
726

727
    /**
728
     * Opens URL in new window/tab
729
     * @param url - URL to open
730
     */
731
    void open(String url);
732

733
    /**
734
     * Adds browser window resize listener
735
     * @param listener - Resize listener
736
     * @return Registration for removing listener
737
     */
738
    Registration addBrowserWindowResizeListener(ComponentEventListener<BrowserWindowResizeEvent> listener);
739
}
740

741
/**
742
 * Result of JavaScript execution
743
 */
744
interface PendingJavaScriptResult {
745
    /**
746
     * Handles result as string
747
     * @param handler - Result handler
748
     */
749
    void then(SerializableConsumer<String> handler);
750

751
    /**
752
     * Handles result as JSON
753
     * @param handler - Result handler
754
     * @param errorHandler - Error handler
755
     */
756
    void then(SerializableConsumer<JsonValue> handler, SerializableConsumer<String> errorHandler);
757
}
758
```
759

760
**Examples:**
761

762
```java
763
Page page = UI.getCurrent().getPage();
764

765
// Simple execution
766
page.executeJs("console.log('Hello from Java')");
767

768
// With parameters
769
page.executeJs("console.log($0)", "Parameter value");
770

771
// Handle result
772
page.executeJs("return window.innerWidth")
773
    .then(Integer.class, width -> {
774
        Notification.show("Window width: " + width);
775
    });
776

777
// Set page title
778
page.setTitle("My Application - Dashboard");
779

780
// Open URL in new window
781
page.open("https://vaadin.com");
782
```
783

784
## Frontend Integration
785

786
Annotations for CSS and JavaScript module imports.
787

788
```java { .api }
789
/**
790
 * Annotation for importing CSS files
791
 */
792
@Target({ElementType.TYPE})
793
@Retention(RetentionPolicy.RUNTIME)
794
@interface CssImport {
795
    /**
796
     * CSS file path
797
     * @return Path to CSS file
798
     */
799
    String value();
800

801
    /**
802
     * Theme for CSS (e.g., "lumo")
803
     * @return Theme name
804
     */
805
    String themeFor() default "";
806

807
    /**
808
     * Include parameter for conditional imports
809
     * @return Include parameter
810
     */
811
    String include() default "";
812
}
813

814
/**
815
 * Annotation for importing JavaScript modules
816
 */
817
@Target({ElementType.TYPE})
818
@Retention(RetentionPolicy.RUNTIME)
819
@interface JsModule {
820
    /**
821
     * JavaScript module path
822
     * @return Path to JS module
823
     */
824
    String value();
825
}
826

827
/**
828
 * Annotation for NPM package dependencies
829
 */
830
@Target({ElementType.TYPE})
831
@Retention(RetentionPolicy.RUNTIME)
832
@interface NpmPackage {
833
    /**
834
     * NPM package name
835
     * @return Package name
836
     */
837
    String value();
838

839
    /**
840
     * Package version
841
     * @return Version string
842
     */
843
    String version();
844
}
845
```
846

847
**Examples:**
848

849
```java
850
// Custom CSS import
851
@Route("styled")
852
@CssImport("./styles/custom-styles.css")
853
public class StyledView extends VerticalLayout {
854
    // View implementation
855
}
856

857
// Scoped CSS for component
858
@CssImport(
859
    value = "./styles/grid-custom.css",
860
    themeFor = "vaadin-grid"
861
)
862
public class GridView extends VerticalLayout {
863
    // Grid with custom styling
864
}
865

866
// JavaScript module import
867
@Route("custom")
868
@JsModule("./scripts/custom-component.js")
869
public class CustomView extends VerticalLayout {
870
}
871

872
// NPM package dependency
873
@NpmPackage(value = "lodash", version = "^4.17.21")
874
public class UtilityView extends VerticalLayout {
875
}
876
```
877