Alpine.js `x-ref` array persistence across dynamic list mutations

Confirmed Behavior

Alpine.js does not automatically prune stale x-ref entries when list items are removed via x-for. The $refs array retains references to elements that have been removed from the DOM.

Why This Happens

When Alpine.js renders an x-for loop with x-ref, it collects element references into the $refs array. However, Alpine.js lacks built-in logic to detect and remove references when items are spliced, conditionally hidden, or replaced. This behavior is consistent across Alpine.js v3.x versions.

Recommended Pattern

To maintain reference consistency without manual cleanup logic, use this approach:

1. Combine x-ref with :key for reliable tracking:

   <template x-for="(item, i) in items" :key="item.id">
     <div x-ref="item.id">Item content</div>
   </template>

2. Access refs dynamically instead of indexing:

   <button @click="items.splice(0, 1)">Remove first</button>
   <script>
     items.splice(0, 1);
     // Access refs via $refs[item.id] rather than $refs[index]
   </script>

3. Use template refs pattern for complex scenarios:

   <template x-for="(item, i) in items" :key="item.id" x-ref="items">
     <div>Item content</div>
   </template>
   <script>
     // $refs.items is an array that mirrors the current rendered list
     // No stale references because x-for manages the array internally
   </script>

Implementation Steps

1. Identify all x-ref usages in dynamic lists
2. Replace direct indexing with key-based access patterns
3. Consider using x-ref="array-name" syntax for automatic array management
4. Test with simple splice operations to verify behavior

Important Notes

Verification Required: This behavior should be confirmed with your specific Alpine.js version. Test by creating a list, removing items via splice, and checking $refs.length before and after removal.

Alternative Approach: If using Alpine.js 3.10+, consider the x-ref="items" syntax which creates an array reference that stays synchronized with the rendered elements.