# useScrollOverflow

## Usage

Tracks scroll overflow state for a horizontally scrollable container. Returns a ref callback and state booleans that update as the user scrolls or the container resizes. Uses scroll event listeners and ResizeObserver for reactive updates. Tolerance of 1px is applied to avoid sub-pixel false positives.

`scrollRef` is a function ref, so bind it with `:ref="scrollRef"`. Give the container `overflow-x: auto` or `overflow-x: scroll`; the hook only reads the edges the container already has.

```ts
import { useScrollOverflow } from '@astryx-vue/core'
```

```vue
<script setup lang="ts">
import { useScrollOverflow } from '@astryx-vue/core'

const { hasOverflow, overflowEnd, overflowStart, scrollRef } = useScrollOverflow()
</script>

<template>
  <div class="rail">
    <button :disabled="!overflowStart">
      Back
    </button>
    <div :ref="scrollRef" class="rail-track">
      <slot />
    </div>
    <button :disabled="!overflowEnd">
      More
    </button>
  </div>
</template>
```

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Use to show/hide scroll navigation buttons or fade edges on carousels and horizontal lists. |
| Do | Apply the `scrollRef` to a container with `overflow-x: auto` or `overflow-x: scroll`. |
| Don't | Use for vertical scroll tracking; this hook only measures horizontal overflow. |

## Parameters

None. The hook reads the element it is bound to.

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `scrollRef` | `(node: HTMLElement \| null) => void` | Function ref to attach to the horizontally scrollable container element. |
| `overflowStart` | `Ref<boolean>` | Whether content overflows the start edge (left in LTR, right in RTL). |
| `overflowEnd` | `Ref<boolean>` | Whether content overflows the end edge (right in LTR, left in RTL). |
| `hasOverflow` | `Ref<boolean>` | Whether the container has any scroll overflow at all (`scrollWidth > clientWidth`). |