vueuse · OrbisK · Dec 24, 2024 · Jan 15, 2025 · Jan 16, 2025 · May 16, 2025
diff --git a/packages/core/index.ts b/packages/core/index.ts
@@ -62,6 +62,8 @@ export * from './useGeolocation'
 export * from './useIdle'
 export * from './useImage'
 export * from './useInfiniteScroll'
+export * from './useInputCaretPosition'
+export * from './useInputSelection'
 export * from './useIntersectionObserver'
 export * from './useKeyModifier'
 export * from './useLocalStorage'

diff --git a/packages/core/useEventListener/index.ts b/packages/core/useEventListener/index.ts
@@ -12,6 +12,7 @@ interface InferEventTarget<Events> {
 }

 export type WindowEventName = keyof WindowEventMap
+export type HTMLElementEventName = keyof HTMLElementEventMap
 export type DocumentEventName = keyof DocumentEventMap

 export interface GeneralEventListener<E = Event> {

diff --git a/packages/core/useInputCaretPosition/demo.vue b/packages/core/useInputCaretPosition/demo.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { ref, useTemplateRef } from 'vue'
+import { useInputCaretPosition } from '..'
+
+const input = useTemplateRef<HTMLInputElement>('input')
+
+const { position } = useInputCaretPosition(input)
+
+const inputValue = ref('')
+</script>
+
+<template>
+  <div>
+    <input ref="input" v-model="inputValue" type="text" placeholder="Type here">
+    caret position: {{ position }}
+  </div>
+</template>
diff --git a/packages/core/useInputCaretPosition/index.browser.test.ts b/packages/core/useInputCaretPosition/index.browser.test.ts
@@ -0,0 +1,54 @@
+import { page, userEvent } from '@vitest/browser/context'
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import { defineComponent, nextTick } from 'vue'
+import { useInputCaretPosition } from '.'
+
+const simpleInput = defineComponent({
+  template: `<input data-testId="input" value="vueuse is cool!">`,
+})
+
+describe('useInputCaretPosition', () => {
+  it('should be defined', () => {
+    expect(useInputCaretPosition).toBeDefined()
+  })
+
+  it('should return the initial position', async () => {
+    const wrapper = mount(simpleInput)
+    const { position } = useInputCaretPosition(wrapper.element)
+    expect(position.value).toMatchInlineSnapshot(`15`)
+  })
+
+  it('should update the position selection change', async ({ onTestFailed, onTestFinished }) => {
+    const screen = page.render(simpleInput)
+    onTestFailed(() => screen.unmount())
+    onTestFinished(() => screen.unmount())
+    const input = screen.getByTestId('input')
+    const element = input.element() as HTMLInputElement
+    const { position } = useInputCaretPosition(element)
+
+    await userEvent.click(input)
+    expect(position.value).toMatchInlineSnapshot(`15`)
+    await userEvent.keyboard('[ArrowLeft][ArrowLeft]')
+    expect(position.value).toMatchInlineSnapshot(`13`)
+  })
+
+  it('should update the element when updating the refs', async ({ onTestFailed, onTestFinished }) => {
+    const screen = page.render(simpleInput)
+    onTestFailed(() => screen.unmount())
+    onTestFinished(() => screen.unmount())
+    const input = screen.getByTestId('input')
+    const element = input.element() as HTMLInputElement
+
+    const { position } = useInputCaretPosition(element)
+
+    expect(element.selectionStart).toMatchInlineSnapshot(`15`)
+    expect(element.selectionEnd).toMatchInlineSnapshot(`15`)
+
+    position.value = 2
+
+    await nextTick()
+    expect(element.selectionStart).toMatchInlineSnapshot(`2`)
+    expect(element.selectionEnd).toMatchInlineSnapshot(`2`)
+  })
+})
diff --git a/packages/core/useInputCaretPosition/index.md b/packages/core/useInputCaretPosition/index.md
@@ -0,0 +1,33 @@
+---
+category: Unknown
+---
+
+# useCaretPosition
+
+Reactive caret position of an input element.
+
+::: warning
+[`onselectionchange`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/selectionchange_event) for
+inputs is still an experimental browser feature. It may have different behaviors across different
+browsers. (e.g. Chrome will fire `onselectionchange` event when the input is
+mounted ([Chromium Issue](https://issues.chromium.org/issues/389368412)), leading to unexpected initial values)
+:::
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useInputCaretPosition } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const input = useTemplateRef<HTMLInputElement>('input')
+
+const { position } = useInputCaretPosition(input)
+</script>
+
+<template>
+  <div>
+    <input ref="input" type="text" placeholder="Type here">
+  </div>
+</template>
+```
diff --git a/packages/core/useInputCaretPosition/index.ts b/packages/core/useInputCaretPosition/index.ts
@@ -0,0 +1,31 @@
+import type { MaybeElementRef } from '../unrefElement'
+import type { UseInputSelectionOptions } from '../useInputSelection'
+import { computed } from 'vue'
+import { useInputSelection } from '../useInputSelection'
+
+export interface UseInputCaretPostionOptions extends UseInputSelectionOptions {
+
+}
+
+export function useInputCaretPosition<T extends (HTMLInputElement | HTMLTextAreaElement)>(target: MaybeElementRef<T | null | undefined>, options: UseInputCaretPostionOptions = {}) {
+  const { start, end, direction } = useInputSelection<T>(target, options)
+
+  const position = computed<T['selectionStart'] | T['selectionEnd']>({
+    set(value) {
+      start.value = value
+      end.value = value
+    },
+    get() {
+      if (direction.value === 'backward') {
+        return start.value
+      }
+      return end.value
+    },
+  })
+
+  return {
+    position,
+  }
+}
+
+export type UseInputCaretPositionReturn = ReturnType<typeof useInputCaretPosition>
diff --git a/packages/core/useInputSelection/demo.vue b/packages/core/useInputSelection/demo.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import { stringify } from '@vueuse/docs-utils'
+import { reactive, ref, useTemplateRef } from 'vue'
+import { useInputSelection } from '.'
+
+const input = useTemplateRef('input')
+const textarea = useTemplateRef('textarea')
+
+const { start, end, direction } = useInputSelection(input)
+const selectionTextarea = reactive(useInputSelection(textarea))
+
+const value = ref('VueUse is cool')
+
+const text = stringify(reactive({ start, end, direction }))
+const textTextarea = stringify(selectionTextarea)
+
+function selectFirst() {
+  input.value?.focus()
+  start.value = 0
+  end.value = 5
+}
+</script>
+
+<template>
+  <div>
+    <input ref="input" v-model="value" type="text" placeholder="Type here">
+    <button @click.prevent="() => selectFirst()">
+      select first 5
+    </button>
+    <pre lang="yaml">{{ text }}</pre>
+    <textarea ref="textarea" v-model="value" type="text" placeholder="Type here" />
+    <pre lang="yaml">{{ textTextarea }}</pre>
+  </div>
+</template>
diff --git a/packages/core/useInputSelection/index.browser.test.ts b/packages/core/useInputSelection/index.browser.test.ts
@@ -0,0 +1,58 @@
+import { page, userEvent } from '@vitest/browser/context'
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import { defineComponent, nextTick } from 'vue'
+import { useInputSelection } from '.'
+
+const simpleInput = defineComponent({
+  template: `<input data-testId="input" value="vueuse is cool!">`,
+})
+
+// TODO: this tests current chrome behavior, initial values are not consistent across browsers
+describe('useInputSelection', () => {
+  it('should be defined', () => {
+    expect(useInputSelection).toBeDefined()
+  })
+
+  it('should return the initial position', async () => {
+    const wrapper = mount(simpleInput)
+    const { start, end, direction } = useInputSelection(wrapper.element)
+    expect(start.value).toMatchInlineSnapshot(`15`)
+    expect(end.value).toMatchInlineSnapshot(`15`)
+    expect(direction.value).toMatchInlineSnapshot(`"forward"`)
+  })
+
+  it('should update the position selection change', async ({ onTestFailed, onTestFinished }) => {
+    const screen = page.render(simpleInput)
+    onTestFailed(() => screen.unmount())
+    onTestFinished(() => screen.unmount())
+    const input = screen.getByTestId('input')
+    const element = input.element() as HTMLInputElement
+    const { start, end, direction } = useInputSelection(element)
+
+    // simulating select all
+    await userEvent.tripleClick(input)
+    expect(element.selectionStart).toMatchInlineSnapshot(`0`)
+    expect(element.selectionEnd).toMatchInlineSnapshot(`15`)
+    expect(start.value).toMatchInlineSnapshot(`0`)
+    expect(end.value).toMatchInlineSnapshot(`15`)
+    expect(direction.value).toMatchInlineSnapshot(`"forward"`)
+  })
+
+  it('should update the element when updating the refs', async ({ onTestFailed, onTestFinished }) => {
+    const screen = page.render(simpleInput)
+    onTestFailed(() => screen.unmount())
+    onTestFinished(() => screen.unmount())
+    const input = screen.getByTestId('input')
+    const element = input.element() as HTMLInputElement
+    const { start, end, direction } = useInputSelection(element)
+
+    start.value = 1
+    end.value = 2
+    direction.value = 'backward'
+    await nextTick()
+    expect(element.selectionStart).toMatchInlineSnapshot(`1`)
+    expect(element.selectionEnd).toMatchInlineSnapshot(`2`)
+    expect(element.selectionDirection).toMatchInlineSnapshot(`"backward"`)
+  })
+})
diff --git a/packages/core/useInputSelection/index.md b/packages/core/useInputSelection/index.md
@@ -0,0 +1,31 @@
+---
+category: Unknown
+---
+
+# useInputSelection
+
+Reactive selection state of an input element.
+
+::: warning
+[`onselectionchange`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/selectionchange_event) for
+inputs is still an experimental browser feature. It may have different behaviors across different
+browsers. (e.g. Chrome will fire `onselectionchange` event when the input is
+mounted ([Chromium Issue](https://issues.chromium.org/issues/389368412)), leading to unexpected initial values)
+:::
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useInputSelection } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+
+const input = useTemplateRef('input')
+
+const { start, end, direction } = useInputSelection(input)
+</script>
+
+<template>
+  <input ref="input" type="text" placeholder="Type here">
+</template>
+```
diff --git a/packages/core/useInputSelection/index.ts b/packages/core/useInputSelection/index.ts
@@ -0,0 +1,65 @@
+import type { ShallowRef } from 'vue'
+import type { MaybeElementRef } from '../unrefElement'
+import type { HTMLElementEventName } from '../useEventListener'
+import { computed, shallowRef, watch } from 'vue'
+import { unrefElement } from '../unrefElement'
+import { useEventListener } from '../useEventListener'
+
+// todo: maybe remove input and foucsin events if feature is stable
+export const inputSelectionDefaultEvents: HTMLElementEventName[] = ['selectionchange', 'input', 'focusin']
+
+export interface UseInputSelectionOptions {
+  /**
+   * Events to trigger the selection tracking.
+   *
+   * @default ['selectionchange', 'input', 'focusin']
+   */
+  events?: HTMLElementEventName[]
+}
+
+export interface UseInputSelectionReturn<T extends (HTMLInputElement | HTMLTextAreaElement)> {
+  start: ShallowRef<T['selectionStart']>
+  end: ShallowRef<T['selectionEnd']>
+  direction: ShallowRef<T['selectionDirection']>
+}
+
+/**
+ * Track or set the selection state of a DOM input or textarea element.
+ *
+ * @param target
+ * @param options
+ */
+export function useInputSelection<T extends (HTMLInputElement | HTMLTextAreaElement)>(target: MaybeElementRef<T | null | undefined>, options: UseInputSelectionOptions = {}): UseInputSelectionReturn<T> {
+  const {
+    events = inputSelectionDefaultEvents,
+  } = options
+
+  const el = computed(() => unrefElement(target))
+
+  const start = shallowRef<T['selectionStart'] | null>(el.value?.selectionStart ?? null)
+  const end = shallowRef<T['selectionEnd'] | null>(el.value?.selectionEnd ?? null)
+  const direction = shallowRef<T['selectionDirection'] | null>(el.value?.selectionDirection ?? null)
+
+  watch([() => start.value, () => end.value, () => direction.value], ([s, e, d]) => {
+    const el = unrefElement(target)
+    if (!el)
+      return
+    el.setSelectionRange(s, e, d)
+  }, { flush: 'post' })
+
+  useEventListener(target, events, (e) => {
+    const el = e.target as T
+    if (start.value !== el.selectionStart)
+      start.value = el.selectionStart
+    if (end.value !== el.selectionEnd)
+      end.value = el.selectionEnd
+    if (direction.value !== el.selectionDirection)
+      direction.value = el.selectionDirection
+  }, { passive: true })
+
+  return {
+    start,
+    end,
+    direction,
+  }
+}
-Original file line number
+Diff line change
@@ -0,0 +1,17 @@
+    <script setup lang="ts">
+    import { ref, useTemplateRef } from 'vue'
+    import { useInputCaretPosition } from '..'
+    const input = useTemplateRef<HTMLInputElement>('input')
+    const { position } = useInputCaretPosition(input)
+    const inputValue = ref('')
     Check failure
        on line 9
        in packages/core/useInputCaretPosition/demo.vue
  



  
      
View workflow job for this annotation

  

  
    
    GitHub Actions / lint
  

  
    
      
    
  

  
    Usage of ref() is restricted. Use shallowRef() or deepRef() instead
  




        
  
  
      
  
  
    Check failure
        on line 9
        in packages/core/useInputCaretPosition/demo.vue
  



  
      
View workflow job for this annotation

  

  
    
    GitHub Actions / autofix
  

  
    
      
    
  

  
    Usage of ref() is restricted. Use shallowRef() or deepRef() instead
+    </script>
+    <template>
+      <div>
+        <input ref="input" v-model="inputValue" type="text" placeholder="Type here">
+        caret position: {{ position }}
+      </div>
+    </template>