Package com.vaadin.flow.component.page

Class Page

java.lang.Object
com.vaadin.flow.component.page.Page
All Implemented Interfaces:
Serializable
public class Page extends Object implements Serializable
Represents the web page open in the browser, containing the UI it is connected to.
Since:
1.0
Author:
Vaadin Ltd
See Also:

  • Constructor Details

    • Page

      public Page(UI ui)
      Creates a page instance for the given UI.
      Parameters:
      ui - the UI that this page instance is connected to

  • Method Details

    • setTitle

      public void setTitle(String title)
      Sets the page title. The title is displayed by the browser e.g. as the title of the browser window or tab.

      To clear the page title, use an empty string.

      Parameters:
      title - the page title to set, not null

    • setColorScheme

      public void setColorScheme(ColorScheme.Value colorScheme)
      Sets the color scheme for the page.

      The color scheme is applied via both a theme attribute and the color-scheme CSS property on the html element. The theme attribute allows CSS to target different color schemes (e.g., html[theme~="dark"]), while the color-scheme property ensures browser UI adaptation works even for custom themes that don't define their own color-scheme CSS rules.

      Parameters:
      colorScheme - the color scheme to set (e.g., ColorScheme.Value.DARK, ColorScheme.Value.LIGHT), or null to reset to NORMAL

    • getColorScheme

      public ColorScheme.Value getColorScheme()
      Gets the color scheme for the page.

      Note that this method returns the server-side cached value and will not detect color scheme changes made directly via JavaScript or browser developer tools.

      Returns:
      the color scheme value, never null

    • addStyleSheet

      public Registration addStyleSheet(String url)
      Adds the given style sheet to the page and ensures that it is loaded successfully.

      Relative URLs are interpreted as relative to the static web resources directory. So if the url value is "some.js" and src/main/webapp is used as a location for static web resources (which is the default location) then the file system path for the resource should be src/main/webapp/some.js.

      You can prefix the URL with context:// to make it relative to the context path or use an absolute URL to refer to files outside the frontend directory.

      For component related style sheet dependencies, you should use the @StyleSheet annotation.

      Is is guaranteed that style sheet will be loaded before the first page load. For more options, refer to addStyleSheet(String, LoadMode)

      Parameters:
      url - the URL to load the style sheet from, not null
      Returns:
      a registration object that can be used to remove the style sheet

    • addStyleSheet

      public Registration addStyleSheet(String url, LoadMode loadMode)
      Adds the given style sheet to the page and ensures that it is loaded successfully.

      Relative URLs are interpreted as relative to the static web resources directory. So if the url value is "some.js" and src/main/webapp is used as a location for static web resources (which is the default location) then the file system path for the resource should be src/main/webapp/some.js.

      You can prefix the URL with context:// to make it relative to the context path or use an absolute URL to refer to files outside the frontend directory.

      For component related style sheet dependencies, you should use the @StyleSheet annotation.

      Parameters:
      url - the URL to load the style sheet from, not null
      loadMode - determines dependency load mode, refer to LoadMode for details
      Returns:
      a registration object that can be used to remove the style sheet

    • addJavaScript

      public void addJavaScript(String url)
      Adds the given JavaScript to the page and ensures that it is loaded successfully.

      Relative URLs are interpreted as relative to the static web resources directory. So if the url value is "some.js" and src/main/webapp is used as a location for static web resources (which is the default location) then the file system path for the resource should be src/main/webapp/some.js.

      You can prefix the URL with context:// to make it relative to the context path or use an absolute URL to refer to files outside the frontend directory.

      For component related JavaScript dependencies, you should use the @JavaScript annotation.

      Is is guaranteed that script will be loaded before the first page load. For more options, refer to addJavaScript(String, LoadMode)

      Parameters:
      url - the URL to load the JavaScript from, not null

    • addJavaScript

      public void addJavaScript(String url, LoadMode loadMode)
      Adds the given JavaScript to the page and ensures that it is loaded successfully.

      Relative URLs are interpreted as relative to the static web resources directory. So if the url value is "some.js" and src/main/webapp is used as a location for static web resources (which is the default location) then the file system path for the resource should be src/main/webapp/some.js.

      You can prefix the URL with context:// to make it relative to the context path or use an absolute URL to refer to files outside the frontend directory.

      For component related JavaScript dependencies, you should use the @JavaScript annotation.

      Parameters:
      url - the URL to load the JavaScript from, not null
      loadMode - determines dependency load mode, refer to LoadMode for details

    • addJsModule

      public void addJsModule(String url)
      Adds the given external JavaScript module to the page and ensures that it is loaded successfully.

      If the JavaScript modules do not need to be added dynamically, you should use the @JsModule annotation instead.

      Parameters:
      url - the URL to load the JavaScript module from, not null

    • addDynamicImport

      public void addDynamicImport(String expression)
      Adds a dynamic import using a JavaScript expression which is supposed to return a JavaScript Promise.

      No change will be applied on the client side until resulting Promise of the expression is completed. It behaves like other dependencies (addJavaScript(String), addJsModule(String), etc.)

      Parameters:
      expression - the JavaScript expression which return a Promise

    • executeJs

      public PendingJavaScriptResult executeJs(String expression, Object... parameters)
      Asynchronously runs the given JavaScript expression in the browser.

      The expression is executed in an async JavaScript method, so you can utilize await syntax when consuming JavaScript API returning a Promise. The returned PendingJavaScriptResult can be used to retrieve the return value from the JavaScript expression. If a Promise is returned in the JavaScript expression, PendingJavaScriptResult will report the resolved value once it becomes available. If no return value handler is registered, the return value will be ignored.

      Return values from JavaScript can be automatically deserialized into Java objects. All types supported by Jackson for JSON deserialization are supported as return values, including custom bean classes.

      The given parameters will be available to the expression as variables named $0, $1, and so on. All types supported by Jackson for JSON serialization are supported as parameters. Special cases:

      • Element (will be sent as a DOM element reference to the browser if the server-side element instance is attached when the invocation is sent to the client, or as null if not attached)
      • BaseJsonNode (sent as-is without additional wrapping)
      Note that the parameter variables can only be used in contexts where a JavaScript variable can be used. You should for instance do 'prefix' + $0 instead of 'prefix$0' and value[$0] instead of value.$0 since JavaScript variables aren't evaluated inside strings or property names.
      Parameters:
      expression - the JavaScript expression to invoke
      parameters - parameters to pass to the expression
      Returns:
      a pending result that can be used to get a value returned from the expression

    • executeJs

      @Deprecated public PendingJavaScriptResult executeJs(String expression, Serializable[] parameters)
      Deprecated.
      Use executeJs(String, Object...) instead. This method exists only for binary compatibility.
      Executes the given JavaScript expression in the browser.
      Parameters:
      expression - the JavaScript expression to execute
      parameters - parameters to pass to the expression
      Returns:
      a pending result that can be used to get a value returned from the expression

    • getHistory

      public History getHistory()
      Gets a representation of window.history for this page.
      Returns:
      the history representation

    • reload

      public void reload()
      Reloads the page in the browser.

    • windowSizeSignal

      public Signal<WindowSize> windowSizeSignal()
      Returns a signal that tracks the current browser window size.

      The signal is lazily initialized on first access and automatically updates when the browser window is resized. The initial value uses dimensions from ExtendedClientDetails if available, otherwise defaults to 0x0.

      The returned signal is read-only.

      Returns:
      a read-only signal with the current window size

    • addBrowserWindowResizeListener

      public Registration addBrowserWindowResizeListener(BrowserWindowResizeListener resizeListener)
      Adds a new BrowserWindowResizeListener to this UI. The listener will be notified whenever the browser window within which this UI resides is resized.
      Parameters:
      resizeListener - the listener to add, not null
      Returns:
      a registration object for removing the listener
      See Also:

    • requestWakeLock

      public void requestWakeLock()
      Requests the browser to keep the screen awake using the Screen Wake Lock API. This prevents the screen from dimming or locking, which is useful for dashboards, kiosk applications, and presentations.

      The wake lock is automatically re-acquired when the page becomes visible again after being hidden (e.g., switching tabs and back).

      If the wake lock is released by the browser (e.g., due to low battery), listeners registered with addWakeLockReleaseListener(com.vaadin.flow.function.SerializableRunnable) are notified.

    • releaseWakeLock

      public void releaseWakeLock()
      Releases a previously acquired screen wake lock.

    • isWakeLockActive

      public PendingJavaScriptResult isWakeLockActive()
      Checks whether a screen wake lock is currently active.
      Returns:
      a pending result that resolves to true if a wake lock is active

    • addWakeLockReleaseListener

      public Registration addWakeLockReleaseListener(SerializableRunnable listener)
      Adds a listener that is notified when the screen wake lock is released, either by the browser or by a call to releaseWakeLock().
      Parameters:
      listener - the listener to add, not null
      Returns:
      a registration object for removing the listener

    • pageVisibilitySignal

      public Signal<PageVisibility> pageVisibilitySignal()
      Returns a signal that tracks the current page visibility state.

      The signal is lazily initialized on first access and automatically updates when the browser tab visibility or focus state changes. It distinguishes between three states: fully visible and focused, visible but not focused (e.g. behind another window), and hidden (e.g. background tab or minimized window).

      The returned signal is read-only.

      Returns:
      a read-only signal with the current page visibility

    • screenOrientationSignal

      public Signal<ScreenOrientationData> screenOrientationSignal()
      Returns a signal that tracks the current screen orientation.

      The signal is lazily initialized on first access and automatically updates when the screen orientation changes. The initial value defaults to ScreenOrientation.PORTRAIT_PRIMARY with angle 0.

      The returned signal is read-only.

      Returns:
      a read-only signal with the current screen orientation data

    • lockOrientation

      public PendingJavaScriptResult lockOrientation(ScreenOrientation orientation)
      Locks the screen orientation to the specified type. This requires fullscreen mode in most browsers.

      The returned result resolves when the lock succeeds, or rejects if the browser denies the request (e.g., not in fullscreen mode).

      Parameters:
      orientation - the orientation to lock to, not null
      Returns:
      a pending result that resolves when the orientation is locked

    • unlockOrientation

      public void unlockOrientation()
      Unlocks the screen orientation, allowing it to rotate freely again.

    • open

      public void open(String url)
      Opens the given url in a new tab.
      Parameters:
      url - the URL to open.

    • open

      public void open(String url, String windowName)
      Opens the given URL in a window with the given name.

      The supplied windowName is used as the target name in a window.open call in the client. This means that special values such as "_blank", "_self", "_top", "_parent" have special meaning. An empty or null window name is also a special case.

      "", null and "_self" as windowName all causes the URL to be opened in the current window, replacing any old contents. For downloadable content you should avoid "_self" as "_self" causes the client to skip rendering of any other changes as it considers them irrelevant (the page will be replaced by the response from the URL). This can speed up the opening of a URL, but it might also put the client side into an inconsistent state if the window content is not completely replaced e.g., if the URL is downloaded instead of displayed in the browser.

      "_blank" as windowName causes the URL to always be opened in a new window or tab (depends on the browser and browser settings).

      "_top" and "_parent" as windowName works as specified by the HTML standard.

      Any other windowName will open the URL in a window with that name, either by opening a new window/tab in the browser or by replacing the contents of an existing window with that name.

      Parameters:
      url - the URL to open.
      windowName - the name of the window.

    • setLocation

      public void setLocation(String uri)
      Navigates this page to the given URI. The contents of this page in the browser is replaced with whatever is returned for the given URI.
      Parameters:
      uri - the URI to show

    • setLocation

      public void setLocation(URI uri)
      Navigates this page to the given URI. The contents of this page in the browser is replaced with whatever is returned for the given URI.
      Parameters:
      uri - the URI to show

    • getExtendedClientDetails

      public ExtendedClientDetails getExtendedClientDetails()
      Gets the extended client details, such as screen resolution and time zone information.

      Browser details are automatically collected and sent during UI initialization, making them immediately available. In normal operation, this method returns complete details right after the UI is created.

      If details are not yet available, this method returns a placeholder instance with default values (dimensions set to -1). If you need to fetch the actual values in such cases, use ExtendedClientDetails.refresh(SerializableConsumer) to explicitly retrieve updated values from the browser.

      To refresh the cached values with updated data from the browser at any time, use ExtendedClientDetails.refresh(SerializableConsumer).

      Returns:
      the extended client details (never null)

    • retrieveExtendedClientDetails

      @Deprecated public void retrieveExtendedClientDetails(Page.ExtendedClientDetailsReceiver receiver)
      Deprecated.
      Use getExtendedClientDetails() to get the cached details, or ExtendedClientDetails.refresh(SerializableConsumer) to refresh the cached values.
      Obtain extended client side details, such as time screen and time zone information, via callback. If already obtained, the callback is called directly. Otherwise, a client-side roundtrip will be carried out.
      Parameters:
      receiver - the callback to which the details are provided

    • fetchCurrentURL

      public void fetchCurrentURL(SerializableConsumer<URL> callback)
      Retrieves the current url from the browser. The URL is fetched from the browser in another request asynchronously and passed to the callback. The URL is the full URL that the user sees in the browser (including hash #) and works even when client side routing is used or there is a reverse proxy between the client and the server.

      In case you need more control over the execution you can use executeJs(String, Object...) by passing return window.location.href.

      NOTE: the URL is not escaped, use URL.toURI() to escape it.

      Parameters:
      callback - to be notified when the url is resolved.

    • fetchPageDirection

      public void fetchPageDirection(SerializableConsumer<Direction> callback)
      Retrieves document.dir of the current UI from the browser and passes it to the callback parameter. If the document.dir has not been set explicitly, then Direction.LEFT_TO_RIGHT will be the fallback value.

      Note that direction is fetched from the browser in an asynchronous request and passed to the callback.

      In case you need more control over the execution you can use executeJs(String, Object...) by passing return document.dir.

      Parameters:
      callback - to be notified when the direction is resolved.

    • isShareSupported

      public boolean isShareSupported()
      Returns whether the browser supports the Web Share API (navigator.share).
      Returns:
      true if the browser supports the Web Share API

    • share

      public PendingJavaScriptResult share(String title, String text, String url)
      Invokes the browser's native share dialog using the Web Share API.
      Parameters:
      title - the title to share
      text - the text to share
      url - the URL to share
      Returns:
      a pending result that resolves when the share completes or rejects if the user cancels or sharing fails
      Throws:
      UnsupportedOperationException - if the browser does not support the Web Share API

    • requestFullscreen

      public void requestFullscreen()
      Requests that the browser display the entire page in fullscreen mode.

      This calls document.documentElement.requestFullscreen() which fullscreens the entire page. Themes and overlay components (such as Notification and ComboBox popups) work correctly in this mode.

      Note that browsers require transient user activation (e.g., a button click) to enter fullscreen mode. Calling this method from a server push or view constructor will likely not work.

      See Also:

    • exitFullscreen

      public void exitFullscreen()
      Exits fullscreen mode if the page is currently in fullscreen.

      This calls document.exitFullscreen() on the browser. If a component was previously fullscreened via Component.requestFullscreen(), it will be automatically restored to its original position.

      See Also:

    • isFullscreenEnabled

      public PendingJavaScriptResult isFullscreenEnabled()
      Checks if the browser supports fullscreen mode.

      Returns a PendingJavaScriptResult that resolves to a boolean. Use it like: 

       page.isFullscreenEnabled().then(Boolean.class, enabled -> {
     if (enabled) {
         page.requestFullscreen();
     }
 });
      Returns:
      a pending result that resolves to true if fullscreen is supported

    • addFullscreenChangeListener

      public Registration addFullscreenChangeListener(FullscreenChangeListener listener)
      Adds a listener that is notified when the fullscreen state changes.

      The listener is called when the page enters or exits fullscreen mode, whether triggered programmatically or by the user (e.g., pressing Escape).

      Parameters:
      listener - the listener to add, not null
      Returns:
      a registration object for removing the listener
      See Also: