⬅️ Back to Table of Contents

📄 useFocusTrap

📊 Analysis Summary

Metric	Count
🔧 Functions	5
📦 Imports	18
🟢 Vue Composition API	2
📐 Interfaces	2

📚 Table of Contents

• Imports
• Vue Composition API
• Functions
• Interfaces

🛠️ File Location:

📂 packages/integrations/useFocusTrap/index.ts

📦 Imports

Name	Source
Arrayable	@vueuse/core
Fn	@vueuse/core
MaybeComputedElementRef	@vueuse/core
ActivateOptions	focus-trap
DeactivateOptions	focus-trap
FocusTrap	focus-trap
Options	focus-trap
MaybeRefOrGetter	vue
ShallowRef	vue
toArray	@vueuse/core
tryOnScopeDispose	@vueuse/core
unrefElement	@vueuse/core
notNullish	@vueuse/shared
createFocusTrap	focus-trap
computed	vue
shallowRef	vue
toValue	vue
watch	vue

---

Vue Composition API

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

---

Functions

useFocusTrap(target: MaybeRefOrGetter<Arrayable<MaybeRefOrGe…, options: UseFocusTrapOptions): UseFocusTrapReturn

Reactive focus-trap

See: https://vueuse.org/useFocusTrap

Raw JSDoc

/**
 * Reactive focus-trap
 *
 * @see https://vueuse.org/useFocusTrap
 */

Calls:

• shallowRef (from vue)
• trap.activate
• trap.deactivate
• trap.pause
• trap.unpause
• computed (from vue)
• toValue (from vue)
• toArray(_targets) .map((el) => { const _el = toValue(el) return typeof _el === 'string' ? _el : unrefElement(_el) }) .filter
• watch (from vue)
• createFocusTrap (from focus-trap)
• options.onActivate
• options.onDeactivate
• activate
• trap?.updateContainerElements
• tryOnScopeDispose (from @vueuse/core)
• deactivate

Internal Comments:

// create the trap (x3)
// Apply if user provided onActivate option
// Apply if user provided onDeactivate option
// Focus if immediate is set to true
// get the active state of the trap (x2)
// update the container elements (x4)
// if the trap is not active and immediate is set to true, activate the trap
// Cleanup on unmount (x3)

Code

export function useFocusTrap(
  target: MaybeRefOrGetter<Arrayable<MaybeRefOrGetter<string> | MaybeComputedElementRef>>,
  options: UseFocusTrapOptions = {},
): UseFocusTrapReturn {
  let trap: undefined | FocusTrap

  const { immediate, ...focusTrapOptions } = options
  const hasFocus = shallowRef(false)
  const isPaused = shallowRef(false)

  const activate = (opts?: ActivateOptions) => trap && trap.activate(opts)
  const deactivate = (opts?: DeactivateOptions) => trap && trap.deactivate(opts)

  const pause = () => {
    if (trap) {
      trap.pause()
      isPaused.value = true
    }
  }

  const unpause = () => {
    if (trap) {
      trap.unpause()
      isPaused.value = false
    }
  }

  const targets = computed(() => {
    const _targets = toValue(target)
    return toArray(_targets)
      .map((el) => {
        const _el = toValue(el)
        return typeof _el === 'string' ? _el : unrefElement(_el)
      })
      .filter(notNullish)
  })

  watch(
    targets,
    (els) => {
      if (!els.length)
        return
      if (!trap) {
        // create the trap
        trap = createFocusTrap(els, {
          ...focusTrapOptions,
          onActivate(params) {
            hasFocus.value = true

            // Apply if user provided onActivate option
            if (options.onActivate)
              options.onActivate(params)
          },
          onDeactivate(params) {
            hasFocus.value = false

            // Apply if user provided onDeactivate option
            if (options.onDeactivate)
              options.onDeactivate(params)
          },
        })

        // Focus if immediate is set to true
        if (immediate)
          activate()
      }
      else {
        // get the active state of the trap
        const isActive = trap?.active

        // update the container elements
        trap?.updateContainerElements(els)

        // if the trap is not active and immediate is set to true, activate the trap
        if (!isActive && immediate) {
          activate()
        }
      }
    },
    { flush: 'post' },
  )

  // Cleanup on unmount
  tryOnScopeDispose(() => deactivate())

  return {
    hasFocus,
    isPaused,
    activate,
    deactivate,
    pause,
    unpause,
  }
}

Internal helpers

Declared inside another function in this file.

activate(opts: ActivateOptions): any

Parameters:

• opts ActivateOptions

Returns: any

Code

(opts?: ActivateOptions) => trap && trap.activate(opts)

deactivate(opts: DeactivateOptions): any

Parameters:

• opts DeactivateOptions

Returns: any

Code

(opts?: DeactivateOptions) => trap && trap.deactivate(opts)

pause(): void

Returns: void

Calls:

• trap.pause

Code

() => {
    if (trap) {
      trap.pause()
      isPaused.value = true
    }
  }

unpause(): void

Returns: void

Calls:

• trap.unpause

Code

() => {
    if (trap) {
      trap.unpause()
      isPaused.value = false
    }
  }

---

Interfaces

UseFocusTrapOptions

Interface Code

export interface UseFocusTrapOptions extends Options {
  /**
   * Immediately activate the trap
   */
  immediate?: boolean
}

Properties

Name	Type	Optional	Description
immediate	boolean	✓	not shown

UseFocusTrapReturn

Interface Code

export interface UseFocusTrapReturn {
  /**
   * Indicates if the focus trap is currently active
   */
  hasFocus: ShallowRef<boolean>

  /**
   * Indicates if the focus trap is currently paused
   */
  isPaused: ShallowRef<boolean>

  /**
   * Activate the focus trap
   *
   * @see https://github.com/focus-trap/focus-trap#trapactivateactivateoptions
   * @param opts Activate focus trap options
   */
  activate: (opts?: ActivateOptions) => void

  /**
   * Deactivate the focus trap
   *
   * @see https://github.com/focus-trap/focus-trap#trapdeactivatedeactivateoptions
   * @param opts Deactivate focus trap options
   */
  deactivate: (opts?: DeactivateOptions) => void

  /**
   * Pause the focus trap
   *
   * @see https://github.com/focus-trap/focus-trap#trappause
   */
  pause: Fn

  /**
   * Unpauses the focus trap
   *
   * @see https://github.com/focus-trap/focus-trap#trapunpause
   */
  unpause: Fn
}

Properties

Name	Type	Optional	Description
hasFocus	ShallowRef<boolean>	✗	not shown
isPaused	ShallowRef<boolean>	✗	not shown
activate	(opts?: ActivateOptions) => void	✗	not shown
deactivate	(opts?: DeactivateOptions) => void	✗	not shown
pause	Fn	✗	not shown
unpause	Fn	✗	not shown

---

Generated by Syntax Scribe