feat: Add varargs-based scrollIntoView API (#22591)

Artur- · web-flow · commit 46e8c23a8ba2 · 2025-10-30T18:03:29.000+02:00
Allows doing
```
component.scrollIntoView(ScrollIntoViewOption.Behavior.SMOOTH, ScrollIntoViewOption.Block.END, ScrollIntoViewOption.Inline.CENTER);
```

without creating an intermediate options object. Consistent with the `focus(...)` API
diff --git a/flow-server/src/main/java/com/vaadin/flow/component/Component.java b/flow-server/src/main/java/com/vaadin/flow/component/Component.java
@@ -796,18 +796,45 @@ protected Locale getLocale() {
     /**
      * Scrolls the current component into the visible area of the browser
      * window.
+     * <p>
+     * This method can be called with no arguments for default browser behavior,
+     * or with one or more {@link ScrollIntoViewOption} values to control
+     * scrolling behavior:
+     * <ul>
+     * <li>{@link ScrollIntoViewOption.Behavior} - controls whether scrolling is
+     * instant or smooth</li>
+     * <li>{@link ScrollIntoViewOption.Block} - controls vertical alignment of
+     * the element</li>
+     * <li>{@link ScrollIntoViewOption.Inline} - controls horizontal alignment
+     * of the element</li>
+     * </ul>
+     * <p>
+     * Examples:
+     *
+     * <pre>
+     * component.scrollIntoView(ScrollIntoViewOption.Behavior.SMOOTH);
+     * component.scrollIntoView(ScrollIntoViewOption.Block.END);
+     * component.scrollIntoView(ScrollIntoViewOption.Behavior.SMOOTH,
+     *         ScrollIntoViewOption.Block.END,
+     *         ScrollIntoViewOption.Inline.CENTER);
+     * </pre>
+     *
+     * @param options
+     *            zero or more scroll options
      */
-    public void scrollIntoView() {
-        scrollIntoView(null);
+    public void scrollIntoView(ScrollIntoViewOption... options) {
+        getElement().scrollIntoView(options);
     }
 
     /**
      * Scrolls the current component into the visible area of the browser
      * window.
      *
+     * @deprecated Use {@link #scrollIntoView(ScrollIntoViewOption...)} instead
      * @param scrollOptions
      *            options to define the scrolling behavior
      */
+    @Deprecated(since = "25.0", forRemoval = true)
     public void scrollIntoView(ScrollOptions scrollOptions) {
         getElement().scrollIntoView(scrollOptions);
     }
diff --git a/flow-server/src/main/java/com/vaadin/flow/component/ScrollIntoViewOption.java b/flow-server/src/main/java/com/vaadin/flow/component/ScrollIntoViewOption.java
@@ -0,0 +1,188 @@
+/*
+ * Copyright 2000-2025 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;
+
+import java.io.Serializable;
+
+import tools.jackson.databind.node.ObjectNode;
+
+import com.vaadin.flow.internal.JacksonUtils;
+
+/**
+ * Marker interface for scrollIntoView options.
+ * <p>
+ * Implementations of this interface can be passed to
+ * {@link com.vaadin.flow.dom.Element#scrollIntoView(ScrollIntoViewOption...)}
+ * and {@link Component#scrollIntoView(ScrollIntoViewOption...)}.
+ * <p>
+ * See <a href=
+ * "https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView">Element.scrollIntoView()</a>
+ * for more information.
+ */
+public interface ScrollIntoViewOption extends Serializable {
+
+    /**
+     * Builds an ObjectNode containing the scrollIntoView options for use with
+     * the browser's scrollIntoView() method.
+     * <p>
+     * This method extracts Behavior, Block, and Inline options from the varargs
+     * and builds a JSON object compatible with the browser's
+     * Element.scrollIntoView() API. Returns null if no options are provided.
+     *
+     * @param options
+     *            zero or more scrollIntoView options
+     * @return an ObjectNode with the scrollIntoView options, or null if no
+     *         options are provided
+     */
+    static ObjectNode buildOptions(ScrollIntoViewOption... options) {
+        // Extract options from varargs
+        Behavior behavior = null;
+        Block block = null;
+        Inline inline = null;
+
+        for (ScrollIntoViewOption option : options) {
+            if (option instanceof Behavior) {
+                behavior = (Behavior) option;
+            } else if (option instanceof Block) {
+                block = (Block) option;
+            } else if (option instanceof Inline) {
+                inline = (Inline) option;
+            }
+        }
+
+        // Return null if no options provided
+        if (behavior == null && block == null && inline == null) {
+            return null;
+        }
+
+        // Build options object
+        ObjectNode json = JacksonUtils.createObjectNode();
+
+        if (behavior != null) {
+            json.put("behavior", behavior.getValue());
+        }
+
+        if (block != null) {
+            json.put("block", block.getValue());
+        }
+
+        if (inline != null) {
+            json.put("inline", inline.getValue());
+        }
+
+        return json;
+    }
+
+    /**
+     * Scroll behavior option for scrollIntoView operations.
+     * <p>
+     * Controls whether scrolling is instant or smooth.
+     */
+    enum Behavior implements ScrollIntoViewOption {
+        /**
+         * Scrolling happens instantly in a single jump.
+         */
+        AUTO,
+
+        /**
+         * Scrolling is animated smoothly.
+         */
+        SMOOTH;
+
+        /**
+         * Gets the lowercase string value for this behavior.
+         *
+         * @return the lowercase string representation
+         */
+        public String getValue() {
+            return name().toLowerCase(java.util.Locale.ENGLISH);
+        }
+    }
+
+    /**
+     * Vertical alignment option for scrollIntoView operations.
+     * <p>
+     * Defines the vertical alignment of the element within the visible area.
+     */
+    class Block implements ScrollIntoViewOption {
+        /**
+         * Aligns the element to the top of the scrolling area.
+         */
+        public static final Block START = new Block("start");
+
+        /**
+         * Aligns the element to the center of the scrolling area.
+         */
+        public static final Block CENTER = new Block("center");
+
+        /**
+         * Aligns the element to the bottom of the scrolling area.
+         */
+        public static final Block END = new Block("end");
+
+        /**
+         * Aligns the element to the nearest edge of the scrolling area.
+         */
+        public static final Block NEAREST = new Block("nearest");
+
+        private final String value;
+
+        private Block(String value) {
+            this.value = value;
+        }
+
+        public String getValue() {
+            return value;
+        }
+    }
+
+    /**
+     * Horizontal alignment option for scrollIntoView operations.
+     * <p>
+     * Defines the horizontal alignment of the element within the visible area.
+     */
+    class Inline implements ScrollIntoViewOption {
+        /**
+         * Aligns the element to the left of the scrolling area.
+         */
+        public static final Inline START = new Inline("start");
+
+        /**
+         * Aligns the element to the center of the scrolling area.
+         */
+        public static final Inline CENTER = new Inline("center");
+
+        /**
+         * Aligns the element to the right of the scrolling area.
+         */
+        public static final Inline END = new Inline("end");
+
+        /**
+         * Aligns the element to the nearest edge of the scrolling area.
+         */
+        public static final Inline NEAREST = new Inline("nearest");
+
+        private final String value;
+
+        private Inline(String value) {
+            this.value = value;
+        }
+
+        public String getValue() {
+            return value;
+        }
+    }
+}
diff --git a/flow-server/src/main/java/com/vaadin/flow/component/ScrollOptions.java b/flow-server/src/main/java/com/vaadin/flow/component/ScrollOptions.java
@@ -26,7 +26,14 @@
  * Options for scrollIntoView.
  * <p>
  * See https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
+ *
+ * @deprecated Use
+ *             {@link com.vaadin.flow.dom.Element#scrollIntoView(ScrollIntoViewOption...)}
+ *             with {@link ScrollIntoViewOption.Behavior},
+ *             {@link ScrollIntoViewOption.Block}, and
+ *             {@link ScrollIntoViewOption.Inline} options instead
  **/
+@Deprecated(since = "25.0", forRemoval = true)
 public class ScrollOptions implements Serializable {
     /**
      * Scroll behavior for scrollIntoView.
diff --git a/flow-server/src/main/java/com/vaadin/flow/dom/Element.java b/flow-server/src/main/java/com/vaadin/flow/dom/Element.java
@@ -34,9 +34,11 @@
 import tools.jackson.databind.node.BaseJsonNode;
 import tools.jackson.databind.node.BooleanNode;
 import tools.jackson.databind.node.NullNode;
+import tools.jackson.databind.node.ObjectNode;
 
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.ComponentUtil;
+import com.vaadin.flow.component.ScrollIntoViewOption;
 import com.vaadin.flow.component.ScrollOptions;
 import com.vaadin.flow.component.internal.PendingJavaScriptInvocation;
 import com.vaadin.flow.component.internal.UIInternals.JavaScriptInvocation;
@@ -1836,26 +1838,65 @@ private void informChildrenOfStateChange(boolean enabled, Element element) {
 
     /**
      * Executes the similarly named DOM method on the client side.
+     * <p>
+     * This method can be called with no arguments for default browser behavior,
+     * or with one or more {@link ScrollIntoViewOption} values to control
+     * scrolling behavior:
+     * <ul>
+     * <li>{@link ScrollIntoViewOption.Behavior} - controls whether scrolling is
+     * instant or smooth</li>
+     * <li>{@link ScrollIntoViewOption.Block} - controls vertical alignment of
+     * the element</li>
+     * <li>{@link ScrollIntoViewOption.Inline} - controls horizontal alignment
+     * of the element</li>
+     * </ul>
+     * <p>
+     * Examples:
+     *
+     * <pre>
+     * element.scrollIntoView(); // Default behavior
+     * element.scrollIntoView(ScrollIntoViewOption.Behavior.SMOOTH); // Smooth
+     *                                                               // scrolling
+     * element.scrollIntoView(ScrollIntoViewOption.Block.END); // Scroll to
+     *                                                         // bottom
+     * element.scrollIntoView(ScrollIntoViewOption.Behavior.SMOOTH,
+     *         ScrollIntoViewOption.Block.END,
+     *         ScrollIntoViewOption.Inline.CENTER); // All options
+     * </pre>
      *
+     * @param options
+     *            zero or more scroll options
+     * @return the element
      * @see <a href=
      *      "https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView">Mozilla
      *      docs</a>
-     * @return the element
      */
-    public Element scrollIntoView() {
-        return scrollIntoView(null);
+    public Element scrollIntoView(ScrollIntoViewOption... options) {
+        ObjectNode json = ScrollIntoViewOption.buildOptions(options);
+
+        // Use setTimeout to work on newly created elements
+        if (json == null) {
+            executeJs("setTimeout(function(){$0.scrollIntoView()},0)", this);
+        } else {
+            executeJs("setTimeout(function(){$0.scrollIntoView($1)},0)", this,
+                    json);
+        }
+
+        return getSelf();
     }
 
     /**
      * Executes the similarly named DOM method on the client side.
      *
+     * @deprecated Use {@link #scrollIntoView(ScrollIntoViewOption...)} instead
      * @see <a href=
      *      "https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView">Mozilla
      *      docs</a>
      * @param scrollOptions
      *            the scroll options to pass to the method
      * @return the element
      */
+    @Deprecated(since = "25.0", forRemoval = true)
     public Element scrollIntoView(ScrollOptions scrollOptions) {
         // for an unknown reason, needs to be called deferred to work on a newly
         // created element
diff --git a/flow-server/src/test/java/com/vaadin/flow/component/ComponentTest.java b/flow-server/src/test/java/com/vaadin/flow/component/ComponentTest.java
