|
| 1 | +# useFocusLock |
| 2 | + |
| 3 | +The **`useFocusLock`** hook is an internal hook for Chakra UI Vue used to encapsulate `focus-trap` into an extendable composable hook. |
| 4 | + |
| 5 | +This allows us to compose the behaviour required for focus trapping accessible dialogs and modals into a single hook and can be extended as a component |
| 6 | + |
| 7 | +## Import |
| 8 | + |
| 9 | +```bash |
| 10 | +import { useFocusLock } from "@chakra-ui/c-focus-lock" |
| 11 | +``` |
| 12 | +
|
| 13 | +This composable accepts options to modify the positioning fo the popover as well as the modifiers of the popper. It returns an object of properties that can be used to bind the template refs to the popper instance |
| 14 | +
|
| 15 | +## Usage |
| 16 | +
|
| 17 | +```vue |
| 18 | +<template> |
| 19 | + <chakra.div |
| 20 | + :ref="lock" |
| 21 | + p="4" |
| 22 | + border="4px dashed" |
| 23 | + rounded="lg" |
| 24 | + border-color="gray.400" |
| 25 | + d="inline-block" |
| 26 | + > |
| 27 | + <chakra.p mb="2">Inside focus trap</chakra.p> |
| 28 | + <c-button @click="options.enabled = true" color-scheme="teal"> |
| 29 | + Enable focus lock |
| 30 | + </c-button> |
| 31 | + <c-button :ref="initialFocus" color-scheme="yellow" mx="2" |
| 32 | + >Button 2</c-button |
| 33 | + > |
| 34 | + <c-button color-scheme="blue">Button 3</c-button> |
| 35 | + </chakra.div> |
| 36 | +</template> |
| 37 | + |
| 38 | +<script lang="ts"> |
| 39 | +import { useFocusLock, FocusLockOptions } from '@chakra-ui/c-focus-lock' |
| 40 | +import { defineComponent, reactive } from 'vue' |
| 41 | + |
| 42 | +export default defineComponent({ |
| 43 | + setup() { |
| 44 | + const options: FocusLockOptions = reactive({ |
| 45 | + enabled: true, |
| 46 | + onActivate: () => { |
| 47 | + console.log('focus lock ENABLED') |
| 48 | + }, |
| 49 | + onDeactivate: () => { |
| 50 | + console.log('focus lock DEACTIVATED') |
| 51 | + }, |
| 52 | + }) |
| 53 | + |
| 54 | + const { lock, initialFocus } = useFocusLock(options) |
| 55 | + |
| 56 | + return { |
| 57 | + lock, |
| 58 | + options, |
| 59 | + initialFocus, |
| 60 | + } |
| 61 | + }, |
| 62 | +}) |
| 63 | +</script> |
| 64 | + |
| 65 | + |
| 66 | +``` |
| 67 | +
|
| 68 | +## Props |
| 69 | +These are the options for the `usePopper` composable. These properties are similar to the options listed in the [@popperjs/core](https://popper.js.org/docs/v2/) documentation. |
| 70 | +```ts |
| 71 | +export interface FocusLockOptions { |
| 72 | + /** |
| 73 | + * Determines whether the focus lock is active or inactive |
| 74 | + * @default true |
| 75 | + */ |
| 76 | + enabled: boolean |
| 77 | + /** |
| 78 | + * Invoked handler when focus-lock is activated |
| 79 | + */ |
| 80 | + onActivate?: () => void |
| 81 | + /** |
| 82 | + * Invoked handler when focus-lock is deactivated |
| 83 | + */ |
| 84 | + onDeactivate?: () => void |
| 85 | + /** |
| 86 | + * Invoked handler when focus-lock is activated. |
| 87 | + * |
| 88 | + * By default, an error will be thrown if the focus lock |
| 89 | + * contains no elements in its tab order. With this |
| 90 | + * option you can specify a fallback element to |
| 91 | + * programmatically receive focus if no other |
| 92 | + * tabbable elements are found. |
| 93 | + */ |
| 94 | + fallbackFocus?: FocusTarget |
| 95 | + /** |
| 96 | + * Determines whether focus lock is activated when user clicks outside. |
| 97 | + * @default true |
| 98 | + */ |
| 99 | + clickOutsideDeactivates?: boolean | ((e: MouseEvent) => boolean) |
| 100 | + persistentFocus?: boolean | ((e: MouseEvent) => boolean) |
| 101 | + /** |
| 102 | + * Determines whether to return focus to the previously focused element |
| 103 | + * before the focus-trap was activated, after the focus trap has been deactivated. |
| 104 | + */ |
| 105 | + returnFocus?: boolean |
| 106 | + preventScroll?: boolean |
| 107 | + escapeDeactivates?: boolean |
| 108 | + delayInitialFocus?: boolean |
| 109 | +} |
| 110 | +``` |
0 commit comments