In a Vue 3 `<script setup>` component, how do you define and use a `v-focus` directive, and which hook should do the focusing?

## What a custom directive is Vue ships built-in directives such as `v-model` and `v-show`. A **custom directive** is your own reusable piece of low-level DOM logic attached to an element. It is defined as an object whose optional **hooks** mirror the component lifecycle and receive the element as their first argument. The Vue guide describes them as intended for "reusing logic that involves low-level DOM access on plain elements", and cites `v-focus` as the standard example. ## Defining and using v-focus in script setup ```vue <script setup> const vFocus = { mounted: (el) => el.focus() } </script> <template> <input v-focus placeholder="Search" /> </template> ``` The naming rule does the registration: - In `<script setup>`, any **camelCase variable that starts with the `v` prefix** can be used as a directive. - `vFocus` becomes `v-focus` in the template; `vClickOutside` becomes `v-click-outside`. - An imported directive works the same way: `import { vFocus } from './directives'`. - Without `<script setup>`, you would list it in the `directives` option; app-wide registration goes through `app.directive`. ## Choosing the hook A directive object may define seven hooks. For focusing, the question is when the element is actually in the document: | Hook | When it runs | Can it focus? | |---|---|---| | `created` | before the element's attributes and event listeners are applied | no: not inserted yet | | `beforeMount` | right before the element is inserted into the DOM | no: not inserted yet | | `mounted` | after the owning component and its children are mounted | yes | | `updated` | after the owning component and its children update | yes, but repeatedly | `mounted` is the right hook: it runs once per element insertion, after the element is in the document. ## The function shorthand trap Vue lets you define a directive as a single function. That function is used for **both `mounted` and `updated`**: ```js // looks tidy, but refocuses on every re-render const vFocus = (el) => el.focus() ``` `updated` runs whenever the component that owns the template re-renders, not only when the directive's value changes. So typing in another field of the same form, which updates state and re-renders, would yank focus back to this input. The shorthand suits directives that should re-apply on every update, such as setting a colour from `binding.value`, not one-time actions. ## Why not the autofocus attribute The HTML `autofocus` attribute acts when the page loads. Elements that Vue inserts later, for example a search field revealed by `v-if` or an input inside a dialog opened by a click, do not get focus from it. The directive's `mounted` hook runs whenever Vue inserts the element, so it covers those cases. ## Variations worth knowing 1. **Conditional focus:** pass a value, `v-focus="isEditing"`, and focus only when `binding.value` is true. 2. **Refocus on a change:** add an `updated` hook that compares `binding.value` with `binding.oldValue` and focuses only when it flips to true. 3. **Selecting text:** call `el.select()` after focusing for inline-edit fields. ## Common mistakes - Naming the variable `focus` or `VFocusDirective` and wondering why `v-focus` is unknown. - Using `created` or `beforeMount`, where `focus()` does nothing because the element is not in the document. - Using the function shorthand for a one-time action. - Using a directive where a template ref plus `onMounted` in the same component is simpler; a directive pays off when many components need the same behaviour. ## The full hook order at a glance For one element carrying a directive, the hooks run in this order over its life: 1. `created` — the element exists but its attributes and listeners are not applied yet. 2. `beforeMount` — attributes are applied; the element is about to be inserted. 3. `mounted` — after the owning component and all its children are mounted. 4. `beforeUpdate` and `updated` — once per re-render of the owning component, for as long as the element stays. 5. `beforeUnmount` and `unmounted` — when the element is removed, for example by `v-if`. Step 4 is tied to the **owner's** re-renders, not to the directive's value, which is exactly why a function shorthand repeats its work.