useOverflow
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).
@astryxdesign/core/hooks
Signature
Call shape
useOverflow(itemCount: number, options: UseOverflowOptions = {}): UseOverflowReturnParameters
| Name | Type and behavior |
|---|---|
itemCount | number · requiredTotal number of items to measure for overflow. |
options | UseOverflowOptions · optionalConfiguration object for overflow behavior. |
options.gap | number · optional · default 0Gap between items in pixels. Used in width calculations. |
options.minVisibleItems | number · optional · default 0Minimum number of items to always show, even if they don't fit. |
options.collapseFrom | 'start' | 'end' · optional · default 'end'which end to collapse items from. |
options.behavior | 'observeParent' | 'observeSelf' · optional · default '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 and behavior |
|---|---|
containerRef | React.RefCallback<HTMLElement>Ref callback to attach to the visible container element. |
measureRef | React.RefCallback<HTMLElement>Ref callback to attach to the hidden measurement container that holds all items. |
visibleCount | numberNumber of items that fit in the visible container. |
hasOverflow | booleanWhether any items are overflowing (visibleCount < itemCount). |
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).
- Render all items into the measureRef container (hidden) and only the first visibleCount items into the containerRef container (visible).
- Include an overflow indicator (e.g., "+N more" button) as the last child of the measurement container with a data-overflow-indicator attribute.
- Use for vertical overflow; this hook measures horizontal width only.