API for accessing slot DOM elements

[ivanmem]

Some components cannot change the DOM structure — for example, components used inside tables or other strict layouts where adding a wrapper element would break the markup.

In such cases, the component renders only a <slot /> but still needs access to the actual DOM element provided by that slot.

Right now, this can only be done by reading internal structures like vm.subTree.children, which is unreliable and depends on undocumented internals.

Example of current workaround:

import { computedWithControl } from '@vueuse/core';
import { getCurrentInstance, onMounted, onUpdated } from 'vue';

export function useComponentElements() {
  const vm = getCurrentInstance()!;
  
  const elements = computedWithControl(
    () => null,
    () => {
      const children: any = vm.subTree?.children;
      if (!children) {
        return undefined;
      }
      if (!Array.isArray(children)) {
        return undefined;
      }
      return children?.map((x) => {
        if (!x || x.el instanceof Comment) {
          return undefined;
        }
        if (x.el instanceof Text) {
          return x.el.nextElementSibling;
        }
        return x.el;
      }).filter(Boolean) as HTMLElement[];
    },
  );
  
  onUpdated(elements.trigger);
  onMounted(elements.trigger);
  
  return elements;
}

This works but is fragile and may break in future Vue versions.

Why not use directives?

A common suggestion might be to use custom directives for DOM access. However, directives have significant limitations in this scenario:

1. No Vue component scope — Directives don't have access to the component's reactive state, props, or composables
2. Cannot use VueUse composables — Popular utilities like useResizeObserver, useIntersectionObserver, useElementSize etc. require component context
3. No lifecycle integration — Directives can't easily integrate with component lifecycle hooks like onBeforeUnmount for cleanup
4. Awkward communication — Passing data between directive and component requires workarounds (events, provide/inject, or global state)
5. Type safety issues — Directive bindings are harder to type correctly compared to composables

Directives are great for reusable DOM manipulations across different components, but when a component needs to interact with its own slotted content, a composable-based solution is more natural and maintainable.

Proposed API

It would be helpful to have an official API, for example:

const el = useTemplateRefFromSlot('default')

which would return a ref to the first rendered element from the given slot (or null if empty).

Alternative API could support multiple elements:

const elements = useSlotElements('default') // Ref<HTMLElement[]>

Motivation

Allow components to interact with slotted DOM elements (e.g. attach scroll logic, measure size, or observe mutations) without changing the template structure and without relying on private internals.

This would enable:

• Scroll containers that don't wrap content
• Layout components that measure slotted content
• Accessibility enhancements on slotted elements
• Integration with VueUse and other composable libraries
• Type-safe, maintainable code that won't break with Vue updates

Use Cases

<script setup lang="ts">
import { useSlotElements } from 'vue'
import { useResizeObserver } from '@vueuse/core'

// Access slot content without wrapper
const slotElements = useSlotElements('default')

// Use with VueUse composables
useResizeObserver(slotElements, (entries) => {
  console.log('Slot content resized:', entries)
})
</script>

<template>
  <!-- No wrapper needed -->
  <slot />
</template>