Text v-text

In Vue.js template syntax, alongside the familiar text interpolation using double curly braces {{ }}, the framework provides a dedicated built-in directive for rendering text content: v-text. This article explores the syntax and behavioral characteristics of this directive, and highlights how it differs from both text interpolation and the v-html directive.

The v-text directive is used to bind data from a Vue instance as plain text to an element's text content. Its core characteristic is that any HTML tags present in the data will be treated strictly as ordinary strings and output verbatim, without undergoing any HTML parsing.

The basic syntax is written as follows:

<span v-text="message"></span>

This line of code is functionally equivalent to:

<span>{{ message }}</span>

The following complete example demonstrates how to implement v-text in an application:

<div id="app">
  <p v-text="message"></p>
  <p v-text="count + ' visits'"></p>
</div>

<script>
  const { createApp } = Vue;
  createApp({
    data() {
      return {
        message: 'Hello, Vue!',
        count: 1024
      }
    }
  }).mount('#app');
</script>

The resulting rendered output is:

• First paragraph: Hello, Vue!
• Second paragraph: 1024 visits

As shown, the attribute value of v-text supports simple JavaScript expressions, and the page text updates reactively whenever the bound data changes.

Comparison with Text Interpolation

Although v-text and {{ }} serve a similar purpose, a crucial distinction lies in their replacement behavior.

1. Text interpolation performs a "partial replacement", allowing dynamic data to be mixed seamlessly with static text:

<p>Welcome, {{ username }}</p>

2. v-text performs a "total replacement", completely wiping out any existing inner content or child nodes inside the target element:

<p v-text="username">Welcome</p>
<!-- After rendering, the fallback text "Welcome" is entirely overwritten, displaying only the value of username -->

Therefore, when embedding dynamic data alongside static text, text interpolation should be the preferred choice. v-text becomes more appropriate when the element's entire text content needs to be fully controlled by the data source.

Comparison with v-html

When the bound data contains HTML tags, v-text behaves fundamentally differently from v-html:

data() {
  return {
    rawHtml: '<strong>Important Notice</strong>'
  }
}

<div v-text="rawHtml"></div>
<!-- Page displays: <strong>Important Notice</strong> (tags are escaped into literal text) -->

<div v-html="rawHtml"></div>
<!-- Page displays: Important Notice (rendered with bold styling as the tags are parsed) -->

Because v-html introduces vulnerability to Cross-Site Scripting (XSS) attacks, utilizing v-text for plain text output is a significantly safer choice when handling untrusted content sources.

Important Considerations

When leveraging v-text in practical development, keep the following points in mind:

• Overwrite Warning: Do not write other content or child elements inside the target element hosting the directive, as everything will be overwritten.
• Expressions Only: The attribute value accepts only a single expression; control flow statements such as if or for are not permitted.
• Preventing FOUC: Before Vue compiles templates, text interpolation expressions may briefly display on the page in their raw form (known as template flashing). Elements using v-text, however, remain blank prior to compilation, making it an alternative approach to mitigate flash issues (alongside the v-cloak directive).

Typical Application Scenarios

Given its unique characteristics, v-text is well-suited for the following scenarios:

• When an element's text content must be completely driven by data, with no requirement for static text concatenation.
• When rendering content that might contain special characters or HTML fragments, and you want to force plain-text display to guarantee security.
• When you want to eliminate the template flashing effect of interpolation expressions during early page loading stages.

Ultimately, v-text is a straightforward yet powerful directive. Understanding its differences from interpolation and v-html empowers developers to select the optimal text-rendering approach for various contexts, resulting in safer and more robust Vue applications.