> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: HorizontalScroll Component

## Article: HorizontalScroll Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/mechanisms/horizontal-scroll-component.md

## Article Content:

# HorizontalScroll

_Components/Mechanisms_

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

## Overview

```jsx
() => {
  const [activeId, setActiveId] = React.useState(2);

  return (
    <Box align="center">
      <Box backgroundColor="white" width="500px">
        <HorizontalScroll gradientColor="#FFFFFF">
          <Tabs
            size="small"
            scrollOnOverflow
            activeId={activeId}
            onClick={(value) => setActiveId(Number(value.id))}
            items={[
              { id: 1, title: 'Page into' },
              { id: 2, title: 'Layout' },
              { id: 3, title: 'Permissions' },
              { id: 4, title: 'SEO basics' },
              { id: 5, title: 'Advanced SEO' },
              { id: 6, title: 'Social share' },
            ]}
          />
        </HorizontalScroll>
      </Box>
    </Box>
  );
};
```

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.

```jsx
<Box width="200px">
  <HorizontalScroll gradientColor="#FF0000">
    <Box height="24px" gap="SP2">
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
    </Box>
  </HorizontalScroll>
</Box>;
```

#### Gradient width

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

```jsx
<Box width="200px">
  <HorizontalScroll gradientColor="#FF0000" gradientWidth="120px">
    <Box height="24px" gap="SP2">
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
    </Box>
  </HorizontalScroll>
</Box>;
```

#### Scroll button size

Use `scrollButtonSize` prop to change icon button size.

Choose between:

- `large`
- `medium`
- `small`
- `tiny`

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Box width="200px">
    <HorizontalScroll scrollButtonSize="large">
      <Box height="42px" gap="SP2">
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      </Box>
    </HorizontalScroll>
  </Box>
  <Box width="200px">
    <HorizontalScroll scrollButtonSize="medium">
      <Box height="36px" gap="SP2">
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      </Box>
    </HorizontalScroll>
  </Box>
  <Box width="200px">
    <HorizontalScroll scrollButtonSize="small">
      <Box height="30" gap="SP2">
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      </Box>
    </HorizontalScroll>
  </Box>
  <Box width="200px">
    <HorizontalScroll scrollButtonSize="tiny">
      <Box height="24px" gap="SP2">
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      </Box>
    </HorizontalScroll>
  </Box>
</StorybookComponents.Stack>;
```

#### Scroll button skin

Use `scrollButtonSkin` to choose from the following icon button skins:

- `standard`
- `light`
- `dark`

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Box width="200px">
    <HorizontalScroll scrollButtonSkin="standard">
      <Box height="24px" gap="SP2">
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      </Box>
    </HorizontalScroll>
  </Box>
  <Box width="200px">
    <HorizontalScroll gradientColor="#000" scrollButtonSkin="light">
      <Box height="24px" gap="SP2">
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      </Box>
    </HorizontalScroll>
  </Box>
  <Box width="200px">
    <HorizontalScroll scrollButtonSkin="dark">
      <Box height="24px" gap="SP2">
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
        <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      </Box>
    </HorizontalScroll>
  </Box>
</StorybookComponents.Stack>;
```

#### Scroll debounce

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

```jsx
<Box width="200px">
  <HorizontalScroll scrollDebounce={10}>
    <Box height="24px" gap="SP2">
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
    </Box>
  </HorizontalScroll>
</Box>;
```

#### Scroll distance

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

```jsx
<Box width="200px">
  <HorizontalScroll scrollDistance={2}>
    <Box height="24px" gap="SP2">
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
      <StorybookComponents.Placeholder>Item</StorybookComponents.Placeholder>
    </Box>
  </HorizontalScroll>
</Box>;
```

### Common use case examples

#### Tabs

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

```jsx
() => {
  const [activeId, setActiveId] = React.useState(2);

  return (
    <SidePanel width="500px">
      <SidePanel.Header title="Add elements"></SidePanel.Header>
      <SidePanel.Content noPadding>
        <HorizontalScroll>
          <Tabs
            size="small"
            scrollOnOverflow
            activeId={activeId}
            onClick={(value) => setActiveId(Number(value.id))}
            items={[
              { id: 1, title: 'For you', prefix: <Icons.HomeSmall /> },
              { id: 2, title: 'Stickers', prefix: <Icons.BookmarkSmall /> },
              { id: 3, title: 'Text', prefix: <Icons.TextSmall /> },
              { id: 4, title: 'Images', prefix: <Icons.ImageSmall /> },
              { id: 4, title: 'Icons', prefix: <Icons.HeartSmall /> },
              { id: 5, title: 'Shapes', prefix: <Icons.FavoriteSmall /> },
              {
                id: 6,
                title: 'Designers images',
                prefix: <Icons.ManagePhotosSmall />,
              },
            ]}
          />
        </HorizontalScroll>
        <Divider></Divider>
        <HorizontalScroll>
          <Box padding="24px" gap="SP2">
            <ToggleButton
              border={true}
              selected
              interactive={false}
              size="small"
              labelValue="All"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              size="small"
              border={true}
              labelPlacement="tooltip"
              labelValue="Birthday"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Decorative"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Abstract"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Wedding"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Flowers"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Love"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Scribbles"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Christmas"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Lifestyle"
              shape="pill"
              skin="inverted"
            />
            <ToggleButton
              border={true}
              size="small"
              labelValue="Baby"
              shape="pill"
              skin="inverted"
            />

            <ToggleButton
              border={true}
              size="small"
              labelValue="Frames"
              shape="pill"
              skin="inverted"
            />
          </Box>
        </HorizontalScroll>
      </SidePanel.Content>
    </SidePanel>
  );
};
```

## Code

```jsx
import { HorizontalScroll } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `children` *(required)* | `ReactNode` | — | The content rendered inside the scrollable window. |
| `dataHook` | `string` | — | 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 |
| `edgeWidth` | `string` | `'48px'` | Sets the width of the edge treatment (blur or fade) in pixels, e.g. `'36px'`. |
| `gradientColor` | `string` | — | Has no effect: the scroll edges fade into the background regardless of its color. |
| `gradientWidth` | `string` | — | 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"` | `tiny` | Size of the scroll buttons. |
| `scrollButtonSkin` | `"standard" \| "light" \| "inverted" \| "destructive" \| "premium" \| "dark" \| "transparent" \| "ai"` | `standard` | Skin of the scroll buttons. |
| `scrollButtonVariant` | `"primary" \| "secondary" \| "tertiary"` | `secondary` | Visual prominence of the scroll buttons, passed to the `priority` of the underlying IconButton. |
| `scrollDebounce` | `number` | `20` | The debounce time (in milliseconds) to limit the scroll event rate. |
| `scrollDistance` | `number` | `150` | The number of pixels the scrollable content moves per button press. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { HorizontalScrollUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { HorizontalScrollTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { HorizontalScrollTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { HorizontalScrollTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `leftButtonExists` | Checks if left button exists. |
| `rightButtonExists` | Checks if right button exists. |
| `clickLeftButton` | Clicks left button. |
| `clickRightButton` | Clicks right button. |
| `getScrollPosition` | Retrieves scrollLeft property of the scrollable container. |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns 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](invalid-url)) — 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](invalid-url)) — 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](invalid-url)) — 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](invalid-url)) — 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](invalid-url)) — 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](invalid-url)) — has visual changes
- **1.295.0** (2026-07-03) — feat: custom round scroll buttons with hover shadow ([#16467](invalid-url)) — 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](invalid-url))
- **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](invalid-url))
- **1.168.0** (2025-03-07) — feat: introduce new component ([#14537](invalid-url))