@empathyco/x-components/docs/API-reference/components/scroll/x-components.scroll.md

Empathy X Components

---

title: Scroll

---

# Scroll

Scrollable container that emits scroll related X Events. It exposes all the listeners
and props from the BaseScroll component.

## Props

| Name            | Description                   | Type                | Default                   |
| --------------- | ----------------------------- | ------------------- | ------------------------- |
| <code>id</code> | Id to identify the component. | <code>string</code> | <code>MainScrollId</code> |

## Slots

| Name                 | Description | Bindings<br />(name - type - description) |
| -------------------- | ----------- | ----------------------------------------- |
| <code>default</code> |             | None                                      |

## Events

A list of events that the component will emit:

- [`UserScrolled`](https://github.com/empathyco/x/blob/main/packages/x-components/src/wiring/events.types.ts):
  emitted after the user scrolls in this container. The payload is the scroll top distance in
  pixels.
- [`UserChangedScrollDirection`](https://github.com/empathyco/x/blob/main/packages/x-components/src/wiring/events.types.ts):
  emitted when the user changes the scroll direction. The payload is the new scrolling direction.
- [`UserReachedScrollStart`](https://github.com/empathyco/x/blob/main/packages/x-components/src/wiring/events.types.ts):
  emitted when the user scrolls up to the initial position of the scroll.
- [`UserAlmostReachedScrollEnd`](https://github.com/empathyco/x/blob/main/packages/x-components/src/wiring/events.types.ts):
  emitted when the user is about to reach the bottom part of the scroll.
- [`UserReachedScrollEnd`](https://github.com/empathyco/x/blob/main/packages/x-components/src/wiring/events.types.ts):
  emitted when the user has reached the bottom part of the scroll.

## Examples

The Scroll is a component that wraps the BaseScroll and provides it for a unique id.

### Basic usage

#### Overriding the properties

It renders an element with scroll, with the content passed in the `default slot`.

```vue
<template>
  <Scroll id="exampleScrollId" :throttleMs="50" :distanceToBottom="300">
    <div class="content-scroll">
      <span>content1</span>
      <span>content2</span>
    </div>
  </Scroll>
</template>

<script setup>
import { Scroll } from "@empathyco/x-components/scroll";
</script>
```

#### Using scroll events.

```vue
<template>
  <Scroll
    @scroll="scroll"
    @scroll:direction-change="scrollDirectionChange"
    @scroll:at-start="scrollAtStart"
    @scroll:almost-at-end="scrollAlmostAtEnd"
    @scroll:at-end="scrollAtEnd"
    id="exampleScrollId"
    throttleMs="50"
    distanceToBottom="300"
  >
    <div class="content-scroll">
      <span>content1</span>
      <span>content2</span>
    </div>
  </Scroll>
</template>

<script setup>
import { Scroll } from "@empathyco/x-components/scroll";

function scroll(position) {
  console.log("scroll", position);
}
function scrollDirectionChange(direction) {
  console.log("scroll:direction-change", direction);
}
function scrollAtStart(isAtStart) {
  console.log("scroll:at-start", isAtStart);
}
function scrollAlmostAtEnd(isAlmostAtEnd) {
  console.log("scroll:almost-at-end", isAlmostAtEnd);
}
function scrollAtEnd(isAtEnd) {
  console.log("scroll:at-end", isAtEnd);
}
</script>
```

#### Using XEvents.

You can use the XEvents API to subscribe to events programmatically:

```vue
<template>
  <Scroll throttleMs="50" distanceToBottom="300">
    <div class="content-scroll">
      <span>content1</span>
      <span>content2</span>
    </div>
  </Scroll>
</template>

<script setup>
import { onMounted } from "vue";
import { Scroll } from "@empathyco/x-components/scroll";
import { use$x } from "../../../composables";

const x = use$x();

onMounted(() => {
  x.on("UserScrolled").subscribe((distance) => {
    console.log(distance);
  });
  x.on("UserChangedScrollDirection").subscribe((direction) => {
    console.log(direction);
  });
  x.on("UserReachedScrollStart").subscribe((isAtStart) => {
    console.log(isAtStart);
  });
  x.on("UserAlmostReachedScrollEnd").subscribe((isAlmostAtEnd) => {
    console.log(isAlmostAtEnd);
  });
  x.on("UserReachedScrollEnd").subscribe((isAtEnd) => {
    console.log(isAtEnd);
  });
});
</script>
```