Directive or Component

Three tools overlap here: a component, a custom directive, and a composable. Choosing wrongly is not fatal, but it shows up later as awkward markup, or as props that exist only to pass values through to an element you have hidden.

The question

Does the thing you are building decide what HTML exists? If it renders anything, needs slots, or owns state the user sees, it is a component. If it only acts on an element someone else already wrote, it is a directive. A directive receives the element and brings no markup of its own; that is the whole trade.

Autofocus, click-outside, an IntersectionObserver, an input mask from a third-party library: element behaviour, so directives. A modal, a data table, a field with its label and error message: markup, so components.

Where a composable fits

A composable is a plain function that uses Vue's reactivity and is called from <script setup>. Paired with a template ref it does what a directive does, with full types and a visible call site. Prefer it when there is one element in one component. Prefer a directive when the behaviour has to be applied from markup — to many elements, inside a loop, or by other people's templates. A directive is the only one of the three that can be dropped onto an arbitrary element from outside.

What trips people up

updated runs on every re-render of the host component, not only when the bound value changed. On a component tag, a directive applies to that component's root element, and is ignored with a warning if the component has more than one root node. And directive hooks do not run during server rendering unless the directive defines getSSRProps.

The example is a note field: one line tall to start, growing as the text wraps. The growth is a directive, so the textarea keeps its own id, name and v-model.

<script setup lang="ts">
import { ref } from 'vue'
import type { Directive } from 'vue'

function fit(el: HTMLTextAreaElement) {
  el.style.height = 'auto'
  el.style.height = `${el.scrollHeight}px`
}

const vAutosize: Directive<HTMLTextAreaElement, string> = {
  mounted(el) {
    fit(el)
  },
  updated(el, binding) {
    if (binding.value === binding.oldValue) return
    fit(el)
  }
}

const note = ref('')
</script>

<template>
  <label for="note">Note</label>
  <textarea id="note" v-model="note" v-autosize="note" rows="1" />
</template>

<style scoped>
textarea {
  resize: none;
  overflow: hidden;
}
</style>

<script setup lang="ts">
// AutosizeTextarea.vue
import { nextTick, watch, useTemplateRef } from 'vue'

const model = defineModel<string>({ required: true })
const field = useTemplateRef<HTMLTextAreaElement>('field')

watch(model, async () => {
  await nextTick()
  const el = field.value
  if (!el) return
  el.style.height = 'auto'
  el.style.height = `${el.scrollHeight}px`
})
</script>

<template>
  <textarea ref="field" v-model="model" rows="1" />
</template>

<style scoped>
textarea {
  resize: none;
  overflow: hidden;
}
</style>

// src/composables/useAutosize.ts
import { onMounted, watch } from 'vue'
import type { Ref, ShallowRef } from 'vue'

export function useAutosize(
  el: Readonly<ShallowRef<HTMLTextAreaElement | null>>,
  text: Ref<string>
): void {
  function fit() {
    const node = el.value
    if (!node) return
    node.style.height = 'auto'
    node.style.height = `${node.scrollHeight}px`
  }

  onMounted(fit)
  watch(text, fit, { flush: 'post' })
}

<script setup lang="ts">
import type { Directive } from 'vue'
import CardPanel from './CardPanel.vue'

const vOutline: Directive<HTMLElement, string> = {
  mounted(el, binding) {
    el.style.outline = binding.value
  }
}
</script>

<template>
  <!-- Applies to CardPanel's single root element. -->
  <card-panel v-outline="'2px solid currentColor'" />
</template>