Vue Directives

Vue Directives: Built-in Attributes and Reactive Binding Rules

Vue directives are special HTML attributes starting with v- that apply reactive behavior to DOM elements. When reactive state changes, Vue updates the bound attributes, text, or visibility automatically.

Directives remove the need to write manual DOM selectors or setAttribute calls. You declare what the element should display right inside your <template>, and Vue handles the updates.

flowchart LR
    Expression["Reactive State"] --> Directive["v- Directive"]
    Directive --> Binding["Updated DOM Attribute or Text"]

Essential Built-in Directives

• v-text and Mustaches ({{ }}): Renders plain text safely by escaping HTML characters.
• v-html: Inserts raw HTML strings into an element for trusted rich content.
• v-bind (:): Binds reactive values to standard HTML attributes like href, disabled, or title.
• v-model: Syncs form input values with reactive variables in both directions.
• v-show: Toggles the CSS display property between visible and none.

Practical SFC Directives Example

In <script setup>, declare your reactive refs and bind them in the template using shorthands like : for v-bind and @ for v-on.

<script setup>
import { ref } from 'vue';

const rawHtml = ref('<span style="color: #42b883">Highlighted Notice</span>');
const docsUrl = ref('https://vuejs.org/guide/introduction.html');
const isButtonDisabled = ref(true);
const isVisible = ref(true);
const userNote = ref('Ready to learn directives');
</script>

<template>
  <div class="directives-demo">
    <div v-html="rawHtml"></div>

    <a :href="docsUrl" target="_blank" rel="noopener">Read Vue Docs</a>
    <button :disabled="isButtonDisabled">Locked Action</button>

    <input v-model="userNote" type="text" aria-label="User note" />
    <p v-show="isVisible">Note preview: {{ userNote }}</p>

    <button @click="isVisible = !isVisible">Toggle Preview</button>
  </div>
</template>

Common Mistakes

• Using v-html on Untrusted Input: Rendering user-submitted strings with v-html opens your app to Cross-Site Scripting (XSS) attacks. Use mustache interpolation {{ }} for all untrusted text.
• Passing Static Strings with :: Writing :title="Hello" makes Vue look for a variable named Hello. Omit the colon (title="Hello") for plain string literals.
• Confusing v-show with v-if: v-show always keeps the element in the DOM and only toggles display: none. Use v-if when you want to skip rendering an element completely.

Frequently Asked Questions

Should I write v-bind: or the : shorthand?

Most Vue teams prefer the : shorthand (such as :disabled="isLocked") because it keeps templates short and readable. Both syntaxes compile to the exact same output.

How does boolean attribute binding work with v-bind?

When a bound value is truthy, Vue includes the attribute like disabled. When the value is false, null, or undefined, Vue removes the attribute from the DOM element.

Can one directive take an argument and modifiers?

Yes, directives use colons for arguments and dots for modifiers, such as @submit.prevent="onSubmit". Here, submit is the argument and .prevent is the modifier.