# User scrolled

Learn how to track when a user scrolls the content.

This event tracks when a user scrolls the content. Here, "scroll" is a general term that covers any scrolling interaction, whether it's a mouse wheel, a swipe on a touchscreen, or a keyboard shortcut.

> **Question: How does scroll tracking work?**
>
> The event is recorded 250ms after the user stops scrolling.
>
> If the user reverses scroll direction (e.g., scrolling down then up), the current gesture is recorded immediately and a new one begins, producing separate events for each direction. This ensures each event represents a single-direction movement, keeping the `start` and `end` positions meaningful for analysis.

> **Automatically tracked**
>
> The SDK automatically tracks this event when a user scrolls the content.

## Input properties

This event has no input properties.

## Processed properties

These properties are automatically tracked:

- `start`: `object` (optional)

  The scroll offset at the beginning of the gesture, in pixels.

  This is the distance from the top-left corner of the surface to the top-left corner of the viewport. For example, if the user has scrolled 500 pixels down, `y` is 500.

  > **Maximum scroll value**
  >
  > Even when the user scrolls to the very bottom, `y` does not equal the surface height. That is because `y` tracks the top edge of the viewport, not the bottom edge. The maximum value of `y` is `surfaceSize.height - viewportSize.height`.

  - `x`: `number`

    The horizontal offset from the left edge of the surface, in pixels.

  - `y`: `number`

    The vertical offset from the top edge of the surface, in pixels.

- `end`: `object`

  The scroll offset at the end of the gesture, in pixels.

  This is the distance from the top-left corner of the surface to the top-left corner of the viewport. For example, if the user scrolled to 780 pixels down, `y` is 780.

  > **Maximum scroll value**
  >
  > Even when the user scrolls to the very bottom, `y` does not equal the surface height. That is because `y` tracks the top edge of the viewport, not the bottom edge. The maximum value of `y` is `surfaceSize.height - viewportSize.height`.

  - `x`: `number`

    The horizontal offset from the left edge of the surface, in pixels.

  - `y`: `number`

    The vertical offset from the top edge of the surface, in pixels.

- `surfaceSize`: `object` (optional)

  The total dimensions of the scrollable surface, in pixels.

  This represents the entire scrollable area, not just the visible portion. For example, on a web page, this would be the full document size, including content below the fold. In a mobile app, it would be the entire scrollable screen area.

  - `width`: `number`

    The total width of the surface, in pixels.

  - `height`: `number`

    The total height of the surface, in pixels.

- `viewportSize`: `object` (optional)

  The dimensions of the visible area, in pixels.

  This is the portion of the surface currently visible to the user. For example, on the web, this would be the browser window size. In a mobile app, it would be the device screen size.

  - `width`: `number`

    The width of the visible area, in pixels.

  - `height`: `number`

    The height of the visible area, in pixels.

## Payload examples

Below are some payload examples for this event:

**Processed payload**

```json
{
  "type": "userScrolled",
  "start": {
    "x": 0,
    "y": 150
  },
  "end": {
    "x": 0,
    "y": 780
  },
  "surfaceSize": {
    "width": 1920,
    "height": 5400
  },
  "viewportSize": {
    "width": 1920,
    "height": 1080
  }
}
```

## Explore

- [Analytics](/reference/analytics): Learn how to analyze your dashboards.
- [CQL](/reference/cql/introduction): Learn how to create audiences for personalization and analysis.