HorizontalScroll

Components/Mechanisms

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/horizontalscroll

Overview

Copy

HorizontalScroll is a mechanism that enable scroll for different components like Tabs, Buttons, Tags, etc...

Do

  • Use it to for interactive components.
  • Use it when there's not space to show all the items.

Don't

  • Don't use it for promotional content, use <Carusel/> instead.

Feature examples

Gradient color

Use gradientColor prop to make items transition smoother with the background.

Copy

Gradient width

Use gradientWidth prop to adjust the length of the transition gradient.

Copy

Scroll button size

Use scrollButtonSize prop to change icon button size.

Choose between:

  • large
  • medium
  • small
  • tiny
Copy

Scroll button skin

Use scrollButtonSkin to choose from the following icon button skins:

  • standard
  • light
  • dark
Copy

Scroll debounce

Change the debounce time to limit scroll even rate, by using the scrollDebounce prop.

Copy

Scroll distance

Change the number of pixels the scrollable content moves per button press by using scrollDistance prop.

Copy

Common use case examples

Tabs

<HorizontallScroll/> is commonly used to scroll a list of tabs which is too wide for the parent container.

Copy

Code

Copy

Props

NameTypeDefaultDescription
children (required)ReactNode—The content rendered inside the scrollable window.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
edgeStyle"color" | "blur"'color'Controls the visual treatment of the scroll edges: - blur — content near the edge is progressively blurred - color — content near the edge fades out into the background
edgeWidthstring'48px'Sets the width of the edge treatment (blur or fade) in pixels, e.g. '36px'.
gradientColorstring—Has no effect: the scroll edges fade into the background regardless of its color.
gradientWidthstring—The width of the gradient behind the scroll buttons in pixels, e.g. '36px'
onScrollButtonClick(direction: HorizontalScrollDirection) => void—Defines a callback function which is called when one of the scroll buttons is clicked, with the direction the content scrolls in.
scrollButtonSize"small" | "tiny" | "medium" | "large"tinySize of the scroll buttons.
scrollButtonSkin"standard" | "light" | "inverted" | "destructive" | "premium" | "dark" | "transparent" | "ai"standardSkin of the scroll buttons.
scrollButtonVariant"primary" | "secondary" | "tertiary"secondaryVisual prominence of the scroll buttons, passed to the priority of the underlying IconButton.
scrollDebouncenumber20The debounce time (in milliseconds) to limit the scroll event rate.
scrollDistancenumber150The number of pixels the scrollable content moves per button press.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
leftButtonExistsChecks if left button exists.
rightButtonExistsChecks if right button exists.
clickLeftButtonClicks left button.
clickRightButtonClicks right button.
getScrollPositionRetrieves scrollLeft property of the scrollable container.
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.333.0 (2026-10-06) — feat: new scrollButtonVariant prop sets the scroll buttons' IconButton priority (primary, secondary, tertiary); small, medium and large scroll buttons now show large chevrons. (#17255) — has visual changes
  • 1.332.0 (2026-10-05) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.1 (2026-09-28) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.322.0 (2026-09-09) — feat: Visual breaking change: with edgeStyle="color", content near the scroll buttons now fades into whatever is behind it instead of being covered by a solid color gradient, so it blends with any background. Deprecated: the gradientColor prop, it no longer has an effect and can be removed. (#16864) — has visual changes
  • 1.322.0 (2026-09-09) — fix: with edgeStyle="blur", scrolled content and the edge blur no longer show beyond the scroll buttons — content now fades out before reaching them. (#16864) — has visual changes
  • 1.322.0 (2026-09-09) — fix: the right scroll arrow now disappears when scrolled fully to the end under browser zoom or display scaling (previously it could stay visible forever, e.g. with Tabs scrollOnOverflow). (#16864) — has visual changes
  • 1.313.1 (2026-08-18) — maintenance release, no component-specific changes
  • 1.312.0 (2026-08-14) — fix: scroll buttons are dark with a white chevron in Studio 2.0 (odeditor-dark) instead of light. (#16781) — has visual changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.306.0 (2026-07-31) — feat: new edgeStyle prop controls the treatment of the scroll edges — 'blur' progressively blurs content near the edge, 'color' covers it with a color gradient (together with gradientColor). A new edgeWidth prop sets the width of the edge treatment. Visual breaking change: the default edge treatment is now the blur; pass edgeStyle="color" to keep the previous gradient look. Deprecated: the gradientWidth prop, use edgeWidth instead (it still works and maps to edgeWidth, but logs a deprecation warning). (#16647) — has visual changes
  • 1.295.0 (2026-07-03) — feat: custom round scroll buttons with hover shadow (#16467) — has visual changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.271.0 (2026-04-22) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.205.0 (2025-07-15) — feat: scrollButtonSize and gradientWidth props (#15079)
  • 1.172.0 (2025-03-20) — maintenance release, no component-specific changes
  • 1.171.0 (2025-03-14) — fix: remove use of @testing-library/react from uni driver (#14606)
  • 1.168.0 (2025-03-07) — feat: introduce new component (#14537)

Last updated: 22 October 2026

Did this help?