fix(components)!: consistent exposed refs (#5385)

benjamincanac · web-flow · commit fce2df4e0660 · 2025-11-04T16:45:27.000+01:00
diff --git a/docs/content/docs/2.components/chat-prompt.md b/docs/content/docs/2.components/chat-prompt.md
@@ -186,6 +186,14 @@ async function onSubmit() {
 
 :component-emits
 
+### Expose
+
+When accessing the component via a template ref, you can use the following:
+
+| Name | Type |
+| ---- | ---- |
+| `textareaRef`{lang="ts-type"} | `Ref<HTMLTextAreaElement \| null>`{lang="ts-type"} |
+
 ## Theme
 
 :component-theme
diff --git a/docs/content/docs/2.components/content-search.md b/docs/content/docs/2.components/content-search.md
@@ -151,6 +151,14 @@ It is recommended to wrap the `ContentSearch` component in a [ClientOnly](https:
 
 :component-emits
 
+### Expose
+
+When accessing the component via a template ref, you can use the following:
+
+| Name | Type |
+| ---- | ---- |
+| `commandPaletteRef`{lang="ts-type"} | `Ref<InstanceType<typeof UCommandPalette> \| null>`{lang="ts-type"} |
+
 ## Theme
 
 :component-theme
diff --git a/docs/content/docs/2.components/dashboard-search.md b/docs/content/docs/2.components/dashboard-search.md
@@ -89,6 +89,14 @@ You can disable this behavior by setting the `color-mode` prop to `false`:
 
 :component-emits
 
+### Expose
+
+When accessing the component via a template ref, you can use the following:
+
+| Name | Type |
+| ---- | ---- |
+| `commandPaletteRef`{lang="ts-type"} | `Ref<InstanceType<typeof UCommandPalette> \| null>`{lang="ts-type"} |
+
 ## Theme
 
 :component-theme
diff --git a/docs/content/docs/2.components/form.md b/docs/content/docs/2.components/form.md
@@ -209,19 +209,19 @@ const form = useTemplateRef('form')
 
 This will give you access to the following:
 
-| Name                                                                                                                         | Type                                                                                                                                                                                       |
-|------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `submit()`{lang="ts-type"}                                                                                                   | `Promise<void>`{lang="ts-type"} <br> <div class="text-toned mt-1"><p>Triggers form submission.</p>                                                                                         |
-| `validate(opts: { name?: keyof T \| (keyof T)[], silent?: boolean, nested?: boolean, transform?: boolean })`{lang="ts-type"} | `Promise<T>`{lang="ts-type"} <br> <div class="text-toned mt-1"><p>Triggers form validation. Will raise any errors unless `opts.silent` is set to true.</p>                                 |
-| `clear(path?: keyof T \| RegExp)`{lang="ts-type"}                                                                            | `void` <br> <div class="text-toned mt-1"><p>Clears form errors associated with a specific path. If no path is provided, clears all form errors.</p>                                        |
-| `getErrors(path?: keyof T RegExp)`{lang="ts-type"}                                                                           | `FormError[]`{lang="ts-type"} <br> <div class="text-toned mt-1"><p>Retrieves form errors associated with a specific path. If no path is provided, returns all form errors.</p></div>         |
-| `setErrors(errors: FormError[], name?: keyof T RegExp)`{lang="ts-type"}                                                      | `void` <br> <div class="text-toned mt-1"><p>Sets form errors for a given path. If no path is provided, overrides all errors.</p>                                                           |
-| `errors`{lang="ts-type"}                                                                                                     | `Ref<FormError[]>`{lang="ts-type"} <br> <div class="text-toned mt-1"><p>A reference to the array containing validation errors. Use this to access or manipulate the error information.</p> |
-| `disabled`{lang="ts-type"}                                                                                                   | `Ref<boolean>`{lang="ts-type"}                                                                                                                                                             |
-| `dirty`{lang="ts-type"}                                                                                                      | `Ref<boolean>`{lang="ts-type"} `true` if at least one form field has been updated by the user.                                                                                             |
-| `dirtyFields`{lang="ts-type"}                                                                                                | `DeepReadonly<Set<keyof T>>`{lang="ts-type"} Tracks fields that have been modified by the user.                                                                                            |
-| `touchedFields`{lang="ts-type"}                                                                                              | `DeepReadonly<Set<keyof T>>`{lang="ts-type"} Tracks fields that the user interacted with.                                                                                                  |
-| `blurredFields`{lang="ts-type"}                                                                                              | `DeepReadonly<Set<keyof T>>`{lang="ts-type"} Tracks fields blurred by the user.                                                                                                            |
+| Name | Type |
+| ---- | ---- |
+| `submit()`{lang="ts-type"} | `Promise<void>`{lang="ts-type"} <br> <div class="text-toned mt-1"><p>Triggers form submission.</p> |
+| `validate(opts: { name?: keyof T \| (keyof T)[], silent?: boolean, nested?: boolean, transform?: boolean })`{lang="ts-type"} | `Promise<T>`{lang="ts-type"} <br> <div class="text-toned mt-1"><p>Triggers form validation. Will raise any errors unless `opts.silent` is set to true.</p> |
+| `clear(path?: keyof T \| RegExp)`{lang="ts-type"} | `void` <br> <div class="text-toned mt-1"><p>Clears form errors associated with a specific path. If no path is provided, clears all form errors.</p></div> |
+| `getErrors(path?: keyof T RegExp)`{lang="ts-type"} | `FormError[]`{lang="ts-type"} <br> <div class="text-toned mt-1"><p>Retrieves form errors associated with a specific path. If no path is provided, returns all form errors.</p></div> |
+| `setErrors(errors: FormError[], name?: keyof T RegExp)`{lang="ts-type"} | `void` <br> <div class="text-toned mt-1"><p>Sets form errors for a given path. If no path is provided, overrides all errors.</p></div> |
+| `errors`{lang="ts-type"} | `Ref<FormError[]>`{lang="ts-type"} <br> <div class="text-toned mt-1"><p>A reference to the array containing validation errors. Use this to access or manipulate the error information.</p></div> |
+| `disabled`{lang="ts-type"} | `Ref<boolean>`{lang="ts-type"} |
+| `dirty`{lang="ts-type"} | `Ref<boolean>`{lang="ts-type"} `true` if at least one form field has been updated by the user. |
+| `dirtyFields`{lang="ts-type"} | `DeepReadonly<Set<keyof T>>`{lang="ts-type"} Tracks fields that have been modified by the user. |
+| `touchedFields`{lang="ts-type"} | `DeepReadonly<Set<keyof T>>`{lang="ts-type"} Tracks fields that the user interacted with. |
+| `blurredFields`{lang="ts-type"} | `DeepReadonly<Set<keyof T>>`{lang="ts-type"} Tracks fields blurred by the user. |
 
 ## Theme
 
diff --git a/docs/content/docs/2.components/input-menu.md b/docs/content/docs/2.components/input-menu.md
@@ -855,7 +855,7 @@ When accessing the component via a template ref, you can use the following:
 
 | Name | Type |
 | ---- | ---- |
-| `inputRef`{lang="ts-type"} | `Ref<InstanceType<typeof ComboboxTrigger> \| null>`{lang="ts-type"} |
+| `inputRef`{lang="ts-type"} | `Ref<HTMLInputElement \| null>`{lang="ts-type"} |
 
 ## Theme
 
diff --git a/docs/content/docs/2.components/input-number.md b/docs/content/docs/2.components/input-number.md
@@ -296,9 +296,9 @@ name: 'input-number-slots-example'
 
 When accessing the component via a template ref, you can use the following:
 
-| Name                       | Type                                            |
-| -------------------------- | ----------------------------------------------- |
-| `inputRef`{lang="ts-type"} | `Ref<InstanceType<typeof NumberFieldInput> \| null>`{lang="ts-type"} |
+| Name | Type |
+| ---- | ---- |
+| `inputRef`{lang="ts-type"} | `Ref<HTMLInputElement \| null>`{lang="ts-type"} |
 
 ## Theme
 
diff --git a/docs/content/docs/2.components/input-tags.md b/docs/content/docs/2.components/input-tags.md
@@ -286,9 +286,9 @@ name: 'input-tags-form-field-example'
 
 When accessing the component via a template ref, you can use the following:
 
-| Name                       | Type                                            |
-| -------------------------- | ----------------------------------------------- |
-| `inputRef`{lang="ts-type"} | `Ref<InstanceType<typeof TagsInputInput> \| null>`{lang="ts-type"} |
+| Name | Type |
+| ---- | ---- |
+| `inputRef`{lang="ts-type"} | `Ref<HTMLInputElement \| null>`{lang="ts-type"} |
 
 ## Theme
 
diff --git a/docs/content/docs/2.components/select-menu.md b/docs/content/docs/2.components/select-menu.md
@@ -896,7 +896,7 @@ When accessing the component via a template ref, you can use the following:
 
 | Name | Type |
 | ---- | ---- |
-| `triggerRef`{lang="ts-type"} | `Ref<InstanceType<typeof ComboboxTrigger> \| null>`{lang="ts-type"} |
+| `triggerRef`{lang="ts-type"} | `Ref<HTMLButtonElement \| null>`{lang="ts-type"} |
 
 ## Theme
 
diff --git a/docs/content/docs/2.components/select.md b/docs/content/docs/2.components/select.md
@@ -771,7 +771,7 @@ When accessing the component via a template ref, you can use the following:
 
 | Name | Type |
 | ---- | ---- |
-| `triggerRef`{lang="ts-type"} | `Ref<InstanceType<typeof SelectTrigger> \| null>`{lang="ts-type"} |
+| `triggerRef`{lang="ts-type"} | `Ref<HTMLButtonElement \| null>`{lang="ts-type"} |
 
 ## Theme
 
diff --git a/docs/content/docs/2.components/table.md b/docs/content/docs/2.components/table.md
@@ -678,7 +678,7 @@ This will give you access to the following:
 | Name | Type |
 | ---- | ---- |
 | `tableRef`{lang="ts-type"} | `Ref<HTMLTableElement \| null>`{lang="ts-type"} |
-| `tableApi`{lang="ts-type"} | [`Ref<Table \| null>`{lang="ts-type"}](https://tanstack.com/table/latest/docs/api/core/table#table-api) |
+| `tableApi`{lang="ts-type"} | [`Table`{lang="ts-type"}](https://tanstack.com/table/latest/docs/api/core/table#table-api) |
 
 ## Theme
 
diff --git a/docs/content/docs/2.components/toast.md b/docs/content/docs/2.components/toast.md
@@ -338,6 +338,14 @@ In this example, we use the `AppConfig` to configure the `expand` prop of the `T
 
 :component-emits
 
+### Expose
+
+When accessing the component via a template ref, you can use the following:
+
+| Name | Type |
+| ---- | ---- |
+| `height`{lang="ts-type"} | `Ref<number>`{lang="ts-type"} |
+
 ## Theme
 
 :component-theme
diff --git a/src/runtime/components/AuthForm.vue b/src/runtime/components/AuthForm.vue
@@ -148,17 +148,12 @@ const slots = defineSlots<AuthFormSlots<typeof state, F>>()
 const { t } = useLocale()
 const appConfig = useAppConfig() as AuthForm['AppConfig']
 
-const formRef = useTemplateRef('formRef')
-const passwordVisibility = ref(false)
-const passwordRef = useTemplateRef('passwordRef')
-
 // eslint-disable-next-line vue/no-dupe-keys
 const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.authForm || {}) })())
 
-defineExpose({
-  formRef,
-  state
-})
+const formRef = useTemplateRef('formRef')
+const passwordVisibility = ref(false)
+const passwordRef = useTemplateRef('passwordRef')
 
 function pickFieldProps(field: F) {
   const fields = ['name', 'errorPattern', 'help', 'error', 'hint', 'size', 'required', 'eagerValidation', 'validateOnInputDelay'] as (keyof F)[]
@@ -186,6 +181,11 @@ function omitFieldProps(field: F) {
 
   return omit(field, [...fields, 'label', 'description'])
 }
+
+defineExpose({
+  formRef,
+  state
+})
 </script>
 
 <template>
diff --git a/src/runtime/components/ChatPrompt.vue b/src/runtime/components/ChatPrompt.vue
@@ -38,7 +38,7 @@ export interface ChatPromptSlots extends TextareaSlots {
 </script>
 
 <script setup lang="ts">
-import { computed, useTemplateRef } from 'vue'
+import { computed, toRef, useTemplateRef } from 'vue'
 import { Primitive, useForwardProps } from 'reka-ui'
 import { reactivePick } from '@vueuse/core'
 import { useAppConfig } from '#imports'
@@ -71,6 +71,8 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.chatPrompt |
   variant: props.variant
 }))
 
+const textareaRef = useTemplateRef('textareaRef')
+
 function submit(e: Event) {
   if (model.value.trim() === '') {
     return
@@ -80,15 +82,13 @@ function submit(e: Event) {
 }
 
 function blur(e: Event) {
-  textarea.value?.textareaRef?.blur()
+  textareaRef.value?.textareaRef?.blur()
 
   emits('close', e)
 }
 
-const textarea = useTemplateRef('textarea')
-
 defineExpose({
-  textareaRef: textarea.value?.textareaRef
+  textareaRef: toRef(() => textareaRef.value?.textareaRef)
 })
 </script>
 
@@ -99,7 +99,7 @@ defineExpose({
     </div>
 
     <UTextarea
-      ref="textarea"
+      ref="textareaRef"
       v-model="model"
       :placeholder="placeholder || t('chatPrompt.placeholder')"
       :disabled="Boolean(error) || disabled"
diff --git a/src/runtime/components/CommandPalette.vue b/src/runtime/components/CommandPalette.vue
@@ -360,7 +360,7 @@ const filteredGroups = computed(() => {
 
 const filteredItems = computed(() => filteredGroups.value.flatMap(group => group.items || []))
 
-const listboxRootRef = useTemplateRef('listboxRootRef')
+const rootRef = useTemplateRef('rootRef')
 
 function navigate(item: T) {
   if (!item.children?.length) {
@@ -377,7 +377,7 @@ function navigate(item: T) {
 
   searchTerm.value = ''
 
-  listboxRootRef.value?.highlightFirstItem()
+  rootRef.value?.highlightFirstItem()
 }
 
 function navigateBack() {
@@ -389,7 +389,7 @@ function navigateBack() {
 
   searchTerm.value = ''
 
-  listboxRootRef.value?.highlightFirstItem()
+  rootRef.value?.highlightFirstItem()
 }
 
 function onBackspace() {
@@ -478,7 +478,7 @@ function onSelect(e: Event, item: T) {
     </ListboxItem>
   </DefineItemTemplate>
 
-  <ListboxRoot v-bind="rootProps" ref="listboxRootRef" :selection-behavior="selectionBehavior" :class="ui.root({ class: [props.ui?.root, props.class] })">
+  <ListboxRoot v-bind="rootProps" ref="rootRef" :selection-behavior="selectionBehavior" :class="ui.root({ class: [props.ui?.root, props.class] })">
     <ListboxFilter v-model="searchTerm" as-child>
       <UInput
         :placeholder="placeholder"
diff --git a/src/runtime/components/DashboardSearch.vue b/src/runtime/components/DashboardSearch.vue
@@ -155,6 +155,8 @@ const groups = computed(() => {
   return groups
 })
 
+const commandPaletteRef = useTemplateRef('commandPaletteRef')
+
 function onSelect(item: CommandPaletteItem) {
   if (item.disabled) {
     return
@@ -173,8 +175,6 @@ defineShortcuts({
   }
 })
 
-const commandPaletteRef = useTemplateRef('commandPaletteRef')
-
 defineExpose({
   commandPaletteRef
 })
diff --git a/src/runtime/components/FileUpload.vue b/src/runtime/components/FileUpload.vue
@@ -124,7 +124,7 @@ export interface FileUploadSlots<M extends boolean = false> {
 </script>
 
 <script setup lang="ts" generic="M extends boolean = false">
-import { computed, watch } from 'vue'
+import { computed, toRef, watch } from 'vue'
 import { Primitive, VisuallyHidden } from 'reka-ui'
 import { createReusableTemplate } from '@vueuse/core'
 import { useAppConfig, useLocale } from '#imports'
@@ -260,9 +260,7 @@ watch(modelValue, (newValue) => {
 })
 
 defineExpose({
-  get inputRef() {
-    return inputRef.value?.$el as HTMLInputElement
-  },
+  inputRef: toRef(() => inputRef.value?.$el as HTMLInputElement),
   dropzoneRef
 })
 </script>
diff --git a/src/runtime/components/Input.vue b/src/runtime/components/Input.vue
@@ -62,7 +62,7 @@ export interface InputSlots {
 </script>
 
 <script setup lang="ts" generic="T extends InputValue">
-import { ref, computed, onMounted } from 'vue'
+import { useTemplateRef, computed, onMounted } from 'vue'
 import { Primitive } from 'reka-ui'
 import { useVModel } from '@vueuse/core'
 import { useAppConfig } from '#imports'
@@ -106,7 +106,7 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.input || {})
   fieldGroup: orientation.value
 }))
 
-const inputRef = ref<HTMLInputElement | null>(null)
+const inputRef = useTemplateRef('inputRef')
 
 // Custom function to handle the v-model properties
 function updateInput(value: string | null | undefined) {
diff --git a/src/runtime/components/InputMenu.vue b/src/runtime/components/InputMenu.vue
@@ -189,7 +189,7 @@ export interface InputMenuSlots<
 </script>
 
 <script setup lang="ts" generic="T extends ArrayOrNested<InputMenuItem>, VK extends GetItemKeys<T> | undefined = undefined, M extends boolean = false">
-import { computed, ref, toRef, onMounted, toRaw, nextTick } from 'vue'
+import { computed, useTemplateRef, toRef, onMounted, toRaw, nextTick } from 'vue'
 import { ComboboxRoot, ComboboxArrow, ComboboxAnchor, ComboboxInput, ComboboxTrigger, ComboboxPortal, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxVirtualizer, ComboboxLabel, ComboboxSeparator, ComboboxItem, ComboboxItemIndicator, TagsInputRoot, TagsInputItem, TagsInputItemText, TagsInputItemDelete, TagsInputInput, useForwardPropsEmits, useFilter } from 'reka-ui'
 import { defu } from 'defu'
 import { isEqual } from 'ohash/utils'
@@ -337,7 +337,7 @@ const createItem = computed(() => {
 })
 const createItemPosition = computed(() => typeof props.createItem === 'object' ? props.createItem.position : 'bottom')
 
-const inputRef = ref<InstanceType<typeof ComboboxInput> | null>(null)
+const inputRef = useTemplateRef('inputRef')
 
 function autoFocus() {
   if (props.autofocus) {
@@ -433,7 +433,7 @@ function isInputItem(item: InputMenuItem): item is Exclude<InputMenuItem, InputM
 }
 
 defineExpose({
-  inputRef
+  inputRef: toRef(() => inputRef.value?.$el as HTMLInputElement)
 })
 </script>
 
diff --git a/src/runtime/components/InputNumber.vue b/src/runtime/components/InputNumber.vue
@@ -79,7 +79,7 @@ export interface InputNumberSlots {
 </script>
 
 <script setup lang="ts" generic="T extends InputNumberValue = InputNumberValue">
-import { onMounted, ref, computed } from 'vue'
+import { onMounted, computed, useTemplateRef, toRef } from 'vue'
 import { NumberFieldRoot, NumberFieldInput, NumberFieldDecrement, NumberFieldIncrement, useForwardPropsEmits } from 'reka-ui'
 import { reactivePick, useVModel } from '@vueuse/core'
 import { useAppConfig } from '#imports'
@@ -126,7 +126,7 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.inputNumber
 const incrementIcon = computed(() => props.incrementIcon || (props.orientation === 'horizontal' ? appConfig.ui.icons.plus : appConfig.ui.icons.chevronUp))
 const decrementIcon = computed(() => props.decrementIcon || (props.orientation === 'horizontal' ? appConfig.ui.icons.minus : appConfig.ui.icons.chevronDown))
 
-const inputRef = ref<InstanceType<typeof NumberFieldInput> | null>(null)
+const inputRef = useTemplateRef('inputRef')
 
 function onUpdate(value: number | undefined) {
   if (props.modelModifiers?.optional) {
@@ -159,7 +159,7 @@ onMounted(() => {
 })
 
 defineExpose({
-  inputRef
+  inputRef: toRef(() => inputRef.value?.$el as HTMLInputElement)
 })
 </script>
 
diff --git a/src/runtime/components/InputTags.vue b/src/runtime/components/InputTags.vue
diff --git a/src/runtime/components/Select.vue b/src/runtime/components/Select.vue
diff --git a/src/runtime/components/SelectMenu.vue b/src/runtime/components/SelectMenu.vue
diff --git a/src/runtime/components/Table.vue b/src/runtime/components/Table.vue
diff --git a/src/runtime/components/Textarea.vue b/src/runtime/components/Textarea.vue
diff --git a/src/runtime/components/Toast.vue b/src/runtime/components/Toast.vue
diff --git a/src/runtime/components/Tree.vue b/src/runtime/components/Tree.vue
diff --git a/src/runtime/components/content/ContentSearch.vue b/src/runtime/components/content/ContentSearch.vue
diff --git a/src/runtime/composables/useFileUpload.ts b/src/runtime/composables/useFileUpload.ts
