Skip to content

useFocus

Category
Last Changed
3 months ago

Reactive utility to track or set the focus state of a DOM element. State changes happen on focus and blur events. Setting reactive value from the outside will trigger .focus() and blur() events for true and false values respectively.

Demo

Paragraph that can be focused


Basic Usage

import { useFocus } from '@vueuse/core'

const focusableElement = ref();
const { focused } = useFocus({ target: focusableElement })

watch(focused, focused => {
  if (focused) console.log('input element has been focused')
  else console.log('input element has lost focus')
})
import { useFocus } from '@vueuse/core'

const focusableElement = ref();
const { focused } = useFocus({ target: focusableElement })

watch(focused, focused => {
  if (focused) console.log('input element has been focused')
  else console.log('input element has lost focus')
})

Setting initial focus

To focus element on it's first render one can provide initialValue option with true value. This will trigger .focus() method call on the target element.

import { useFocus } from '@vueuse/core'

const focusableElement = ref();
const focusElementOnFirstRender = true;
const { focused } = useFocus({
  target: focusableElement,
  initialValue: focusElementOnFirstRender,
})
import { useFocus } from '@vueuse/core'

const focusableElement = ref();
const focusElementOnFirstRender = true;
const { focused } = useFocus({
  target: focusableElement,
  initialValue: focusElementOnFirstRender,
})

Change focus state

Changes of the focused reactive ref will automatically trigger .focus() and .blur() calls for true and false values respectively. You can utilize this behavior to e.g. trigger element focus as a result of another action (in an example below - button click).

<template>
  <div>
    <button type="button" @click="focused = true">Click me to focus input below</button>
    <input ref="inputElement" type="text">
  </div>
</template>

<script>
import { ref } from 'vue'
import { useFocus } from '@vueuse/core'

export default {
  setup() {
    const inputElement = ref(null)

    const { focused } = useFocus({ target: inputElement })

    return {
      inputElement,
      focused,
    }
  }
})
</script>
<template>
  <div>
    <button type="button" @click="focused = true">Click me to focus input below</button>
    <input ref="inputElement" type="text">
  </div>
</template>

<script>
import { ref } from 'vue'
import { useFocus } from '@vueuse/core'

export default {
  setup() {
    const inputElement = ref(null)

    const { focused } = useFocus({ target: inputElement })

    return {
      inputElement,
      focused,
    }
  }
})
</script>

Type Declarations

export interface FocusOptions extends ConfigurableWindow {
  /**
   * Initial value. If set true, then focus will be set on the target
   *
   * @default false
   */
  initialValue?: boolean
  /**
   * The target element for the focus and blur events.
   */
  target?: MaybeElementRef
}
export interface FocusReturn {
  /**
   * 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: Ref<boolean>
}
/**
 * Track or set the focus state of a DOM element.
 *
 * @see https://vueuse.org/useFocus
 * @param options
 */
export declare function useFocus(options?: FocusOptions): FocusReturn
export interface FocusOptions extends ConfigurableWindow {
  /**
   * Initial value. If set true, then focus will be set on the target
   *
   * @default false
   */
  initialValue?: boolean
  /**
   * The target element for the focus and blur events.
   */
  target?: MaybeElementRef
}
export interface FocusReturn {
  /**
   * 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: Ref<boolean>
}
/**
 * Track or set the focus state of a DOM element.
 *
 * @see https://vueuse.org/useFocus
 * @param options
 */
export declare function useFocus(options?: FocusOptions): FocusReturn

Source

SourceDemoDocs

Contributors

Anthony Fu
William T. Kirby
Jakub Freisler

Changelog

v6.9.2 on 11/19/2021
47550 - fix: resolve issues when used with v-if (#927)
v6.9.0 on 11/14/2021
355a9 - feat: new function (#818)
useFocus has loaded