VueUseuseFocusTrap
Reactive wrapper for focus-trap.
For more information on what options can be passed, see createOptions in the focus-trap documentation.
Demo
Available in the @vueuse/integrations add-on.Install
bash
npm i focus-trap
npm i focus-trap
Usage
Basic Usage
html
<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
html
<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>
Conditional Rendering
This function can't properly activate focus on elements with conditional rendering using v-if. This is because they do not exist in the DOM at the time of the focus activation. To solve this you need to activate on the next tick.
html
<script setup>
import { nextTick, ref } from 'vue'
const target = ref()
const { activate, deactivate } = useFocusTrap(target, { immediate: true })
const show = ref(false)
const reveal = async () => {
show.value = true
await nextTick()
activate()
}
</script>
<template>
<div>
<div ref="target" v-if="show">...</div>
<button @click="reveal">Reveal and Focus</button>
</div>
</template>
<script setup>
import { nextTick, ref } from 'vue'
const target = ref()
const { activate, deactivate } = useFocusTrap(target, { immediate: true })
const show = ref(false)
const reveal = async () => {
show.value = true
await nextTick()
activate()
}
</script>
<template>
<div>
<div ref="target" v-if="show">...</div>
<button @click="reveal">Reveal and Focus</button>
</div>
</template>
Using Component
With the UseFocusTrap component, Focus Trap will be activated automatically on mounting this component and deactivated on unmount.
html
<script setup>
import { ref } from 'vue'
import { UseFocusTrap } from '@vueuse/integrations/useFocusTrap/component'
const show = ref(false)
</script>
<template>
<UseFocusTrap v-if="show" :options="{ immediate: true }">
<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" :options="{ immediate: true }">
<div class="modal">...</div>
</UseFocusTrap>
</template>
Type Declarations
Show Type Declarations
typescript
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
Soviut
vaakian X
azaleta
Agénor Debriat
Curt Grimes
Roman Harmyder
Alex Kozack
Jordy
wheat