useFocusTrap
Reactive wrapper for focus-trap
For more info on what options can be passed see createOptions in the focus-trap docs.
Demo
available in add-on @vueuse/integrationsUsage
Basic Usage
<script setup>
import { ref } from 'vue'
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
const target = ref()
const { hasFocus, activate, deactivate } = useFocusTrap(target)
</script>
<template>
<div>
<button @click="activate()">Activate</button>
<div ref="target">
<span>Has Focus: {{ hasFocus }}</span>
<input type="text" />
<button @click="deactivate()">Deactivate</button>
</div>
</div>
</template>
<script setup>
import { ref } from 'vue'
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
const target = ref()
const { hasFocus, activate, deactivate } = useFocusTrap(target)
</script>
<template>
<div>
<button @click="activate()">Activate</button>
<div ref="target">
<span>Has Focus: {{ hasFocus }}</span>
<input type="text" />
<button @click="deactivate()">Deactivate</button>
</div>
</div>
</template>
Automatically Focus
<script setup>
import { ref } from 'vue'
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
const target = ref()
const { hasFocus, activate, deactivate } = useFocusTrap(target, { immediate: true })
</script>
<template>
<div>
<div ref="target">...</div>
</div>
</template>
<script setup>
import { ref } from 'vue'
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
const target = ref()
const { hasFocus, activate, deactivate } = useFocusTrap(target, { immediate: true })
</script>
<template>
<div>
<div ref="target">...</div>
</div>
</template>
Using Component
This function can't properly activate focus on elements with conditional rendering. In this case, you can use the UseFocusTrap component. Focus Trap will be activated automatically on mounting this component and deactivated on unmount.
<script setup>
import { ref } from 'vue'
import { UseFocusTrap } from '@vueuse/integrations/useFocusTrap/component'
const show = ref(false)
</script>
<template>
<UseFocusTrap v-if="show">
<div class="modal">...</div>
</UseFocusTrap>
</template>
<script setup>
import { ref } from 'vue'
import { UseFocusTrap } from '@vueuse/integrations/useFocusTrap/component'
const show = ref(false)
</script>
<template>
<UseFocusTrap v-if="show">
<div class="modal">...</div>
</UseFocusTrap>
</template>
Type Declarations
Show Type Declarations
export interface UseFocusTrapOptions extends Options {
/**
* Immediately activate the trap
*/
immediate?: boolean
}
export interface UseFocusTrapReturn {
/**
* Indicates if the focus trap is currently active
*/
hasFocus: Ref<boolean>
/**
* Indicates if the focus trap is currently paused
*/
isPaused: Ref<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
}
/**
* Reactive focus-trap
*
* @see https://vueuse.org/useFocusTrap
* @param target The target element to trap focus within
* @param options Focus trap options
* @param autoFocus Focus trap automatically when mounted
*/
export declare function useFocusTrap(
target: MaybeElementRef,
options?: UseFocusTrapOptions
): UseFocusTrapReturn
export interface UseFocusTrapOptions extends Options {
/**
* Immediately activate the trap
*/
immediate?: boolean
}
export interface UseFocusTrapReturn {
/**
* Indicates if the focus trap is currently active
*/
hasFocus: Ref<boolean>
/**
* Indicates if the focus trap is currently paused
*/
isPaused: Ref<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
}
/**
* Reactive focus-trap
*
* @see https://vueuse.org/useFocusTrap
* @param target The target element to trap focus within
* @param options Focus trap options
* @param autoFocus Focus trap automatically when mounted
*/
export declare function useFocusTrap(
target: MaybeElementRef,
options?: UseFocusTrapOptions
): UseFocusTrapReturn
Source
Contributors
Anthony Fu
Roman Harmyder
Alex Kozack
Jordy
wheat