Skip to content

useFocusTrap

Category
Export Size
718 B
Package
@vueuse/integrations
Last Changed
3 minutes ago

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>

Source

SourceDemoDocs

Contributors

Anthony Fu
Soviut
vaakian X
azaleta
Agénor Debriat
Curt Grimes
Roman Harmyder
Alex Kozack
Jordy
wheat

Changelog

v9.11.0 on 1/17/2023
d5321 - fix(components): mark defineComponent as pure (#2623)
v9.3.1 on 10/17/2022
578bc - feat: enable options in component (#2321)

Released under the MIT License.