Skip to content
On this page

useFocusWithin

Category
Export Size
1.14 kB
Last Changed
4 months ago

Reactive utility to track if an element or one of its decendants has focus. It is meant to match the behavior of the :focus-within CSS pseudo-class. A common use case would be on a form element to see if any of its inputs currently have focus.

Demo

Focus in form: false

Basic Usage

html
<template>
  <form ref="target">
    <input type="text" placeholder="First Name">
    <input type="text" placeholder="Last Name">
    <input type="text" placeholder="Email">
    <input type="text" placeholder="Password">
  </form>
</template>

<script>
import { useFocusWithin } from '@vueuse/core'

const target = ref();
const { focused } = useFocusWithin(target)

watch(focused, focused => {
  if (focused) console.log('Target contains the focused element')
  else console.log('Target does NOT contain the focused element')
})
</script>
<template>
  <form ref="target">
    <input type="text" placeholder="First Name">
    <input type="text" placeholder="Last Name">
    <input type="text" placeholder="Email">
    <input type="text" placeholder="Password">
  </form>
</template>

<script>
import { useFocusWithin } from '@vueuse/core'

const target = ref();
const { focused } = useFocusWithin(target)

watch(focused, focused => {
  if (focused) console.log('Target contains the focused element')
  else console.log('Target does NOT contain the focused element')
})
</script>

Type Declarations

typescript
export interface UseFocusWithinReturn {
  /**
   * True if the element or any of its descendants are focused
   */
  focused: ComputedRef<boolean>
}
/**
 * Track if focus is contained within the target element
 *
 * @see https://vueuse.org/useFocusWithin
 * @param target The target element to track
 * @param options Focus within options
 */
export declare function useFocusWithin(
  target: MaybeElementRef,
  options?: ConfigurableWindow
): UseFocusWithinReturn
export interface UseFocusWithinReturn {
  /**
   * True if the element or any of its descendants are focused
   */
  focused: ComputedRef<boolean>
}
/**
 * Track if focus is contained within the target element
 *
 * @see https://vueuse.org/useFocusWithin
 * @param target The target element to track
 * @param options Focus within options
 */
export declare function useFocusWithin(
  target: MaybeElementRef,
  options?: ConfigurableWindow
): UseFocusWithinReturn

Source

SourceDemoDocs

Contributors

Anthony Fu
sun0day
Mikhailov Nikita
Boris Moiseev
Jelf
William T. Kirby

Changelog

v9.2.0 on 9/5/2022
3316e - fix: change focused typing to ComputedRef (#2073)
v8.9.3 on 7/14/2022
1b871 - fix!: rename type FocusWithinReturn to UseFocusWithinReturn (#1866)
v7.2.0 on 12/8/2021
66a16 - feat: new function (#997)

Released under the MIT License.