feat: Add Fullscreen API wrapping the browser Fullscreen API

Adds Component.requestFullscreen() that uses a wrapper approach to handle
Vaadin theming and overlay components correctly, along with
Page.requestFullscreen() for whole-page fullscreen, Page.exitFullscreen(),
and Page.fullscreenSignal() for reactive observation of the fullscreen
state (FULLSCREEN, NOT_FULLSCREEN, UNSUPPORTED, UNKNOWN).

The signal is seeded from the initial client bootstrap (v-fs parameter)
and updated via a vaadin-fullscreen-change DOM event, mirroring the
page-visibility wiring. The client-side bridge lives in
flow-client/src/main/frontend/Fullscreen.ts, imported from Flow.ts the
same way Geolocation.ts is.

Fixes #21902

Author: Artur-

flow-client/src/main/frontend/Flow.ts

@@ -4,6 +4,7 @@ import {
   type ConnectionStateChangeListener,
   type ConnectionStateStore
 } from '@vaadin/common-frontend';
+import { currentFullscreenState } from './Fullscreen';
 import './Geolocation';
 import { currentVisibility } from './PageVisibility';
 
@@ -544,6 +545,8 @@ export class Flow {
     params['v-cs'] = colorScheme && colorScheme !== 'normal' ? colorScheme : '';
     /* Page visibility — initial state of document.hidden / document.hasFocus() */
     params['v-pv'] = currentVisibility();
+    /* Fullscreen state — initial state of document.fullscreenEnabled / .fullscreenElement */
+    params['v-fs'] = currentFullscreenState();
 
     /* Theme name - detect which theme is in use */
     const computedStyle = getComputedStyle(document.documentElement);

flow-client/src/main/frontend/Fullscreen.ts

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+type VaadinFullscreenState = 'UNSUPPORTED' | 'NOT_FULLSCREEN' | 'FULLSCREEN';
+
+/**
+ * Returns the current fullscreen state synchronously. Used by the bootstrap
+ * path to seed the server-side signal without waiting for a DOM event.
+ */
+export function currentFullscreenState(): VaadinFullscreenState {
+  if (document.fullscreenEnabled !== true) {
+    return 'UNSUPPORTED';
+  }
+  return document.fullscreenElement ? 'FULLSCREEN' : 'NOT_FULLSCREEN';
+}
+
+// Dispatch on document.body so the server-side Page facade (listening on
+// the UI element, which is body) can update its signal.
+function dispatch(state: VaadinFullscreenState): void {
+  document.body.dispatchEvent(new CustomEvent('vaadin-fullscreen-change', { detail: state }));
+}
+
+// Tracks the most recent component-fullscreen setup so the wrapper can be
+// torn down when fullscreen exits (programmatically or via Escape) or when
+// a new fullscreen request supersedes it.
+let activeComponentReset: (() => void) | undefined;
+
+function resetComponentIfActive(): void {
+  if (activeComponentReset) {
+    const fn = activeComponentReset;
+    activeComponentReset = undefined;
+    fn();
+  }
+}
+
+document.addEventListener('fullscreenchange', () => {
+  if (!document.fullscreenElement) {
+    resetComponentIfActive();
+  }
+  dispatch(currentFullscreenState());
+});
+
+const $wnd = window as any;
+$wnd.Vaadin ??= {};
+$wnd.Vaadin.Flow ??= {};
+$wnd.Vaadin.Flow.fullscreen = {
+  /**
+   * Requests fullscreen for the entire page (document.documentElement).
+   * No-op if the browser does not support fullscreen.
+   */
+  requestPageFullscreen(): void {
+    resetComponentIfActive();
+    if (document.fullscreenEnabled !== true) {
+      return;
+    }
+    document.documentElement.requestFullscreen();
+  },
+
+  /**
+   * Requests fullscreen for a specific component by moving it into the
+   * given wrapper element and hiding the rest of the view. Fullscreens
+   * document.documentElement so that Vaadin theming and overlay
+   * components keep working. The component is restored to its original
+   * position on exit (programmatic, Escape, or a superseding request).
+   * No-op if the browser does not support fullscreen.
+   */
+  requestComponentFullscreen(element: HTMLElement, wrapper: HTMLElement): void {
+    resetComponentIfActive();
+    if (document.fullscreenEnabled !== true) {
+      return;
+    }
+    const originalParent = element.parentNode;
+    if (!originalParent) {
+      return;
+    }
+    const placeholder = document.createComment('vaadin-fullscreen-placeholder');
+    originalParent.insertBefore(placeholder, element);
+
+    wrapper.appendChild(element);
+    const viewRoot = wrapper.firstChild as HTMLElement | null;
+    const previousDisplay = viewRoot?.style.display ?? '';
+    if (viewRoot) {
+      viewRoot.style.display = 'none';
+    }
+
+    activeComponentReset = () => {
+      placeholder.parentNode?.insertBefore(element, placeholder);
+      placeholder.remove();
+      if (viewRoot) {
+        viewRoot.style.display = previousDisplay;
+      }
+    };
+
+    document.documentElement.requestFullscreen();
+  },
+
+  /**
+   * Exits fullscreen mode if the page is currently in fullscreen.
+   */
+  exitFullscreen(): void {
+    if (document.fullscreenElement) {
+      document.exitFullscreen();
+    }
+  }
+};
+
+// Empty export to ensure TypeScript emits this as an ES module,
+// which is required for Vite to load it via import.
+export {};

flow-server/src/main/java/com/vaadin/flow/component/Component.java

@@ -903,6 +903,45 @@ public void scrollIntoView(ScrollOptions scrollOptions) {
         getElement().scrollIntoView(scrollOptions);
     }
 
+    /**
+     * Requests that the browser display this component in fullscreen mode.
+     * <p>
+     * Because of how Vaadin theming and overlay components work, this method
+     * does not call {@code requestFullscreen()} on the component's element
+     * directly. Instead, it fullscreens the entire page
+     * ({@code document.documentElement}), moves the component into a wrapper
+     * element, and hides the rest of the view. When fullscreen is exited
+     * (either programmatically via
+     * {@link com.vaadin.flow.component.page.Page#exitFullscreen()} or by the
+     * user pressing Escape), the component is automatically restored to its
+     * original position in the DOM.
+     * <p>
+     * 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 not work. The fullscreen state can be observed
+     * via {@link com.vaadin.flow.component.page.Page#fullscreenSignal()}; calls
+     * made while the state is
+     * {@link com.vaadin.flow.component.page.FullscreenState#UNSUPPORTED
+     * UNSUPPORTED} are no-ops on the client.
+     *
+     * @throws IllegalStateException
+     *             if the component is not attached to a UI
+     * @see com.vaadin.flow.component.page.Page#requestFullscreen()
+     * @see com.vaadin.flow.component.page.Page#exitFullscreen()
+     * @see com.vaadin.flow.component.page.Page#fullscreenSignal()
+     * @see <a href=
+     *      "https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API">MDN
+     *      Fullscreen API</a>
+     */
+    public void requestFullscreen() {
+        UI ui = getUI().orElseThrow(() -> new IllegalStateException(
+                "Component must be attached to the UI to request fullscreen"));
+        Element wrapperElement = ui.getInternals().getWrapperElement();
+        ui.getElement().executeJs(
+                "window.Vaadin.Flow.fullscreen.requestComponentFullscreen($0, $1)",
+                getElement(), wrapperElement);
+    }
+
     /**
      * Traverses the component tree up and returns the first ancestor component
      * that matches the given type.

flow-server/src/main/java/com/vaadin/flow/component/page/ExtendedClientDetails.java

@@ -499,6 +499,7 @@ public static ExtendedClientDetails updateFromJson(UI ui, JsonNode json) {
                 getStringElseNull.apply("v-tn"));
         ui.getInternals().setExtendedClientDetails(details);
         ui.getPage().setPageVisibility(getStringElseNull.apply("v-pv"));
+        ui.getPage().setFullscreenState(getStringElseNull.apply("v-fs"));
         String ga = getStringElseNull.apply("v-ga");
         if (ga != null) {
             try {

flow-server/src/main/java/com/vaadin/flow/component/page/FullscreenState.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.component.page;
+
+import com.vaadin.flow.component.Component;
+
+/**
+ * Represents the fullscreen state of a browser page.
+ * <p>
+ * Wraps the browser's Fullscreen API ({@code document.fullscreenEnabled} and
+ * {@code document.fullscreenElement}) into four observable states: the browser
+ * does not support fullscreen at all, fullscreen is supported but the page is
+ * not in it, the page is currently fullscreen, and an {@link #UNKNOWN} sentinel
+ * used before the first value has arrived from the client.
+ *
+ * @see Page#fullscreenSignal()
+ * @see Page#requestFullscreen()
+ * @see Page#exitFullscreen()
+ * @see Component#requestFullscreen()
+ */
+public enum FullscreenState {
+
+    /**
+     * No value has been reported by the browser yet. Used only as the initial
+     * value of the signal before the first client handshake delivers the real
+     * one. In normal request handling the signal is seeded before any user code
+     * (UI initialization, {@code UIInitListener}, component attach) runs, so
+     * this value is essentially never observed in practice; once a real value
+     * has arrived, the signal never returns to {@code UNKNOWN}.
+     */
+    UNKNOWN,
+
+    /**
+     * The browser does not support fullscreen mode, or the document is not
+     * permitted to enter it. In the browser, this corresponds to
+     * {@code document.fullscreenEnabled} being {@code false}. Calls to
+     * {@link Page#requestFullscreen()} or {@link Component#requestFullscreen()}
+     * are no-ops in this state.
+     */
+    UNSUPPORTED,
+
+    /**
+     * Fullscreen mode is supported and the page is currently not in it. In the
+     * browser, this corresponds to {@code document.fullscreenEnabled} being
+     * {@code true} and {@code document.fullscreenElement} being {@code null}.
+     */
+    NOT_FULLSCREEN,
+
+    /**
+     * The page is currently in fullscreen mode. In the browser, this
+     * corresponds to {@code document.fullscreenElement} being non-{@code null}.
+     */
+    FULLSCREEN
+}

flow-server/src/main/java/com/vaadin/flow/component/page/Page.java

@@ -27,6 +27,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.Direction;
 import com.vaadin.flow.component.UI;
 import com.vaadin.flow.component.dependency.JavaScript;
@@ -66,6 +67,10 @@ public class Page implements Serializable {
             PageVisibility.UNKNOWN);
     private final Signal<PageVisibility> pageVisibilityReadOnly = pageVisibilitySignal
             .asReadonly();
+    private final ValueSignal<FullscreenState> fullscreenSignal = new ValueSignal<>(
+            FullscreenState.UNKNOWN);
+    private final Signal<FullscreenState> fullscreenSignalReadOnly = fullscreenSignal
+            .asReadonly();
 
     /**
      * Creates a page instance for the given UI.
@@ -80,6 +85,10 @@ public Page(UI ui) {
                 .addEventListener("vaadin-page-visibility-change",
                         e -> setPageVisibility(e.getEventDetail(String.class)))
                 .addEventDetail().debounce(100).allowInert();
+        ui.getElement()
+                .addEventListener("vaadin-fullscreen-change",
+                        e -> setFullscreenState(e.getEventDetail(String.class)))
+                .addEventDetail().allowInert();
     }
 
     /**
@@ -551,6 +560,100 @@ void setPageVisibility(String value) {
         }
     }
 
+    /**
+     * Returns a read-only signal that tracks the browser's fullscreen state.
+     * <p>
+     * The signal distinguishes between {@link FullscreenState#FULLSCREEN
+     * FULLSCREEN} (the page is currently in fullscreen),
+     * {@link FullscreenState#NOT_FULLSCREEN NOT_FULLSCREEN} (fullscreen is
+     * supported but the page is not in it), {@link FullscreenState#UNSUPPORTED
+     * UNSUPPORTED} (the browser does not support fullscreen or the document is
+     * not permitted to enter it), and {@link FullscreenState#UNKNOWN UNKNOWN}
+     * (the initial value, replaced with a real one before any user code
+     * observes the signal).
+     * <p>
+     * The signal value is seeded from the initial client bootstrap, so user
+     * code always sees a real value. Subscribe with
+     * {@code Signal.effect(owner, ...)} to react to changes; call
+     * {@code fullscreenSignal().peek()} for a snapshot outside a reactive
+     * context, and {@code .get()} inside one. Use {@link #requestFullscreen()},
+     * {@link Component#requestFullscreen()}, or {@link #exitFullscreen()} to
+     * change the state.
+     * <p>
+     * Note that browsers require transient user activation (e.g. a button
+     * click) to enter fullscreen mode, so the signal will not transition to
+     * {@link FullscreenState#FULLSCREEN FULLSCREEN} in response to a request
+     * from a server push or view constructor.
+     *
+     * @return the read-only fullscreen signal
+     */
+    public Signal<FullscreenState> fullscreenSignal() {
+        return fullscreenSignalReadOnly;
+    }
+
+    /**
+     * Requests that the browser display the entire page in fullscreen mode.
+     * <p>
+     * This calls {@code document.documentElement.requestFullscreen()} on the
+     * browser. Themes and overlay components (such as Notification and ComboBox
+     * popups) work correctly in this mode. Use
+     * {@link Component#requestFullscreen()} to fullscreen a single component
+     * within the page.
+     * <p>
+     * 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 not work. The fullscreen state can be observed
+     * via {@link #fullscreenSignal()}; calls made while the state is
+     * {@link FullscreenState#UNSUPPORTED UNSUPPORTED} are no-ops on the client.
+     *
+     * @see Component#requestFullscreen()
+     * @see #exitFullscreen()
+     * @see #fullscreenSignal()
+     * @see <a href=
+     *      "https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API">MDN
+     *      Fullscreen API</a>
+     */
+    public void requestFullscreen() {
+        executeJs("window.Vaadin.Flow.fullscreen.requestPageFullscreen()");
+    }
+
+    /**
+     * Exits fullscreen mode if the page is currently in fullscreen, otherwise a
+     * no-op.
+     * <p>
+     * If a component was previously fullscreened via
+     * {@link Component#requestFullscreen()}, it is automatically restored to
+     * its original position in the DOM.
+     *
+     * @see #requestFullscreen()
+     * @see Component#requestFullscreen()
+     */
+    public void exitFullscreen() {
+        executeJs("window.Vaadin.Flow.fullscreen.exitFullscreen()");
+    }
+
+    /**
+     * Sets the fullscreen state from a raw client-side value (e.g. from the
+     * bootstrap parameters or from a {@code vaadin-fullscreen-change} DOM
+     * event). {@code null} and unknown values are ignored — the latter is
+     * logged at debug level so a forward-compatible client value does not
+     * silently disappear.
+     *
+     * @param value
+     *            the raw value, or {@code null}
+     */
+    void setFullscreenState(String value) {
+        if (value == null) {
+            return;
+        }
+        try {
+            fullscreenSignal.set(FullscreenState.valueOf(value));
+        } catch (IllegalArgumentException e) {
+            LOGGER.debug("Unknown fullscreen state value from client: {}",
+                    value);
+        }
+    }
+
     /**
      * Opens the given url in a new tab.
      *