# useMergedRefs

## Usage

Combines multiple object or callback refs into one stable callback ref. Use it when a component must forward a consumer ref while also attaching internal refs. Unlike writing an inline function in a `:ref` binding, the callback identity stays stable across unrelated rerenders, so Vue does not detach and reattach the element.

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

Bind the returned function as the element's `:ref`. Every entry in the array receives the same value; `null` and `undefined` slots are skipped, so an optional forwarded ref can sit in the list unconditionally. Vue calls it with `null` when the element unmounts, which clears each target.

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Use useMergedRefs when one element must receive both a forwarded ref and one or more internal refs. |
| Do | Keep the call in `setup` and bind the function it returns, so the element sees the same callback on every render. |
| Don't | Write an inline arrow function in a `:ref` binding; that creates a new callback on every render and forces unnecessary detach and attach work. |

## Parameters

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `refs` | `readonly MergedRef[]` | — | Up to six refs that should all receive the same element. One entry is a `Ref`, a function ref, `null`, or `undefined`; empty slots are skipped. Required. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `mergedRef` | `(value: Element \| ComponentPublicInstance \| null) => void` | A merged callback ref that remains stable for the life of the component. It accepts whatever Vue hands a template ref, including `null` on unmount, and forwards the value to every entry in `refs`. |