⬅️ Back to Table of Contents

📄 useFocus

📊 Analysis Summary

Metric	Count
🔧 Functions	1
📦 Imports	8
🟢 Vue Composition API	3
📐 Interfaces	2

📚 Table of Contents

• Imports
• Vue Composition API
• Functions
• Interfaces

🛠️ File Location:

📂 packages/core/useFocus/index.ts

📦 Imports

Name	Source
WritableComputedRef	vue
ConfigurableWindow	../_configurable
MaybeElementRef	../unrefElement
computed	vue
shallowRef	vue
watch	vue
unrefElement	../unrefElement
useEventListener	../useEventListener

---

Vue Composition API

Name	Type	Reactive Variables	Composables
computed	computed	none	none
computed	computed	none	none
watch	watch	none	none

---

Functions

useFocus(target: MaybeElementRef, options: UseFocusOptions): UseFocusReturn

Track or set the focus state of a DOM element.

Parameters:

• target any: The target element for the focus and blur events.
• options any: No description

See: https://vueuse.org/useFocus

Raw JSDoc

/**
 * Track or set the focus state of a DOM element.
 *
 * @see https://vueuse.org/useFocus
 * @param target The target element for the focus and blur events.
 * @param options
 */

Calls:

• shallowRef (from vue)
• computed (from vue)
• unrefElement (from ../unrefElement)
• useEventListener (from ../useEventListener)
• (event.target as HTMLElement).matches
• targetElement.value?.blur
• targetElement.value?.focus
• watch (from vue)

Code

export function useFocus(target: MaybeElementRef, options: UseFocusOptions = {}): UseFocusReturn {
  const { initialValue = false, focusVisible = false, preventScroll = false } = options

  const innerFocused = shallowRef(false)
  const targetElement = computed(() => unrefElement(target))

  const listenerOptions = { passive: true }
  useEventListener(targetElement, 'focus', (event) => {
    if (!focusVisible || (event.target as HTMLElement).matches?.(':focus-visible'))
      innerFocused.value = true
  }, listenerOptions)
  useEventListener(targetElement, 'blur', () => innerFocused.value = false, listenerOptions)

  const focused = computed({
    get: () => innerFocused.value,
    set(value: boolean) {
      if (!value && innerFocused.value)
        targetElement.value?.blur()
      else if (value && !innerFocused.value)
        targetElement.value?.focus({ preventScroll })
    },
  })

  watch(
    targetElement,
    () => {
      focused.value = initialValue
    },
    { immediate: true, flush: 'post' },
  )

  return { focused }
}

---

Interfaces

UseFocusOptions

Interface Code

export interface UseFocusOptions extends ConfigurableWindow {
  /**
   * Initial value. If set true, then focus will be set on the target
   *
   * @default false
   */
  initialValue?: boolean

  /**
   * Replicate the :focus-visible behavior of CSS
   *
   * @default false
   */
  focusVisible?: boolean

  /**
   * Prevent scrolling to the element when it is focused.
   *
   * @default false
   */
  preventScroll?: boolean
}

Properties

Name	Type	Optional	Description
initialValue	boolean	✓	not shown
focusVisible	boolean	✓	not shown
preventScroll	boolean	✓	not shown

UseFocusReturn

Interface Code

export interface UseFocusReturn {
  /**
   * If read as true, then the element has focus. If read as false, then the element does not have focus
   * If set to true, then the element will be focused. If set to false, the element will be blurred.
   */
  focused: WritableComputedRef<boolean>
}

Properties

Name	Type	Optional	Description
focused	WritableComputedRef<boolean>	✗	not shown

---

Generated by Syntax Scribe