Vue3 v-cloak Directive

Vue3 内置指令Vue3 Built-in Directives

v-cloakThe directive is used to hide uncompiled templates until the component instance is ready.

Basic Explanation

v-cloakThe directive is used to solve the "uncompiled template flash" problem when using DOM templates. When users visit the page, they may see the raw{{ }}mustache tags until the Vue component mounts and renders the content.

v-cloakIt remains on the element until the associated component instance is mounted. Combined with CSS rules, it can hide the raw template during this period.

  • Expected Type: None (does not accept expressions)
  • Purpose: Hides uncompiled templates until the component is ready.

Note: This directive is only needed in setups without a build step.

Basic Usage

When usingv-cloak, you need to combine it with CSS rules:

Example

/* CSS rule: hide elements with v-cloak */
[v-cloak] {
  display: none;
}

Example

<div v-cloak>
  {{ message }}
</div>

When compilation is complete,v-cloakthe attribute is automatically removed from the element, and the element is displayed.

Use Cases

v-cloakMainly used in the following scenarios:

1. Using CDN to Import Vue

When importing Vue via CDN without a build step, during the brief period between page load and the Vue script, the template may not yet be compiled:

Example

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <style>
    [v-cloak] {
      display: none;
    }
  </style>
</head>
<body>
  <div id="app">
    <div v-cloak>
      {{ message }}
    </div>
  </div>

  <script>
    const { createApp } = Vue

    createApp({
      data() {
        return {
          message: 'Hello Vue!'
        }
      }
    }).mount('#app')
  </script>
</body>
</html>

2. Complex Template Structures

For complex templates with multiple data bindings, v-cloak prevents users from seeing unrendered content:

Example

<div v-cloak>
  <h1>{{ title }}</h1>
  <p>Welcome, {{ username }}</p>
  <ul>
    <li v-for="item in items" :key="item.id">
      {{ item.name }}
    </li>
  </ul>
</div>

How v-cloak Works

  1. When the page loads, Vue has not yet been initialized, and thev-cloakattribute exists on the element.
  2. CSS rules[v-cloak] { display: none; }hide these elements.
  3. Vue initializes and compiles the template, creating reactive data.
  4. After the component is mounted, Vue automatically removes thev-cloakattribute.
  5. Elements become visible, displaying the rendered content.

Notes

Only for scenarios without a build step: When using build tools (such as Vite, Webpack), the template is already compiled during the build phase, so v-cloak is not needed.

Example

/* Make sure the v-cloak rule loads before all styles */
/* It is recommended to place the CSS in the head */

<head>
  <style>
    [v-cloak] {
      display: none;
    }
  </style>
</head>

Need to be used with CSS: v-cloak itself does not hide content; it must be combined with CSS rules to take effect.

Differences from Modern Build Tools

When using modern build tools (such as Vite), there is no need for v-cloak because:

  • The template is precompiled during the build phase
  • The JavaScript is inlined or asynchronously loaded after bundling
  • The initial HTML does not contain uncompiled template syntax

Therefore, v-cloak is mainly used in traditional CDN import methods or simple HTML page scenarios.

Vue3 内置指令Vue3 Built-in Directives

Other Extensions