scrollBy

scrollBy is a method available on the Window interface and on scrollable DOM elements. It scrolls the document or a specific element by a relative amount, as opposed to jumping to an absolute position. This makes it useful for implementing programmatic scrolling in response to user actions or UI events.

The common usages include the two-argument form and the options form. For the window or a scrollable element, you can call scrollBy(dx, dy), where dx is the horizontal offset and dy is the vertical offset. Modern browsers also support scrollBy({ left, top, behavior }), where left and top specify offsets and behavior can be 'auto' or 'smooth' to enable animated scrolling. The same forms apply to Element.scrollBy as long as the element has scrollable content.

When behavior is set to 'smooth', the browser animates the scrolling rather than performing an instant jump. If not specified or set to 'auto', the scrolling occurs immediately. The returned value is typically undefined. If the target position is outside the scroll range, the values are clamped to the maximum allowable scroll offset.

scrollBy is distinct from scrollTo, which moves to an absolute coordinate. scrollBy moves by a relative amount from the current position, which can be useful for incremental scrolling, parallax effects, or masonry layouts.

Accessibility considerations include avoiding unnecessary or long smooth scrolling, and respecting user preferences for reduced motion. Compatibility is broad across modern browsers, with two-argument and options forms supported in most environments; older browsers may require the numeric form only.