# useOverflow

## Usage

Measures children rendered in a hidden container to determine how many fit in the available width without flickering. Uses ResizeObserver to react to container and measured-child size changes. The measurement container should hold all items plus an optional overflow indicator element (identified by a `data-overflow-indicator` attribute).

The two containers are template refs here, so bind them with `ref`. `visibleCount`, `rows`, and `rowHeight` are refs you can render right away; `remeasure()` measures again on demand.

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

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

const items = ['One', 'Two', 'Three', 'Four', 'Five']
const { containerRef, hasOverflow, measureRef, visibleCount } = useOverflow(items.length, { gap: 8 })
</script>

<template>
  <div ref="containerRef" class="row">
    <button v-for="item in items.slice(0, visibleCount)" :key="item">
      {{ item }}
    </button>
    <button v-if="hasOverflow">
      +{{ items.length - visibleCount }} more
    </button>
  </div>

  <div ref="measureRef" class="row" inert>
    <button v-for="item in items" :key="item">
      {{ item }}
    </button>
    <button data-overflow-indicator>
      +{{ items.length }} more
    </button>
  </div>
</template>
```

The measured container is painted out of sight, so every item keeps its real width. Put `inert` on it so it stays out of the tab order and the accessibility tree. The visible container renders `visibleCount` items and an overflow indicator of its own, which is not measured.

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Render all items into the `measureRef` container (hidden) and only the first `visibleCount` items into the `containerRef` container (visible). |
| Do | Include an overflow indicator (e.g., "+N more" button) as the last child of the measurement container with a `data-overflow-indicator` attribute. |
| Don't | Use for vertical overflow; this hook measures horizontal width only. |

## Parameters

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `itemCount` | `MaybeRefOrGetter<number>` | — | Total number of items to measure for overflow. |
| `options` | `UseOverflowOptions` | — | Configuration object for overflow behavior. |
| `options.gap` | `number` | `0` | Gap between items in pixels. Used in width calculations. |
| `options.minVisibleItems` | `number` | `0` | Minimum number of items to always show, even if they don't fit. |
| `options.maxVisibleItems` | `number` | — | Upper bound on visible items, even when everything fits. The floor wins when it is larger. |
| `options.maxRows` | `number` | — | Wrap up to this many rows before the rest collapse into the indicator. Omitted or `1` keeps a single row. |
| `options.collapseFrom` | `'start' \| 'end'` | `'end'` | Which end to collapse items from. |
| `options.behavior` | `'observeParent' \| 'observeSelf'` | `'observeSelf'` | Which element to observe for overflow calculations. `observeParent` uses the container's parent element width, allowing the visible container to remain content-sized. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `containerRef` | `Ref` | Template ref to attach to the visible container element. |
| `measureRef` | `Ref` | Template ref to attach to the hidden measurement container that holds all items. |
| `visibleCount` | `Ref<number>` | Number of items that fit in the visible container. |
| `hasOverflow` | `ComputedRef<boolean>` | Whether any items are overflowing (`visibleCount < itemCount`). |
| `rows` | `Ref<number>` | How many rows the visible items occupy. `1` in the single-row mode, `0` when nothing is visible. |
| `rowHeight` | `Ref<number>` | Tallest measured item height, for giving a multi-row container its height. |
| `remeasure` | `() => void` | Measures again. Useful after a test changes widths, or after the collapse state changes. |

## Element overload

`useOverflow(element, isActive)` is the other signature. It measures one box instead of a row of items: it reports whether the element's content is taller than its own visible area, and returns a single `Ref<boolean>`. It is off as long as `isActive` is false.

| Name | Type | Description |
| --- | --- | --- |
| `element` | `Ref` | Template ref of the box to measure. |
| `isActive` | `Ref<boolean>` | Whether to measure. While it is false the result stays `false`. |
| `return` | `Ref<boolean>` | Whether the content is taller than the box. |