Vue's v-once: Render Once, Then Ignore

Why it exists

Vue's reactivity system is powerful but has overhead. For every piece of data, Vue sets up tracking to re-render the DOM when it changes. For content that is known to be static after its initial render, this tracking is unnecessary work. v-once provides a way to opt-out of this reactivity for specific parts of the template, improving performance.

The mental model

Think of v-once as taking a single snapshot. When the component first renders, Vue takes a picture of the element and its children with the current data. From that point on, it only ever shows that snapshot, ignoring any subsequent changes to the underlying data that would normally trigger an update. It freezes that part of the DOM in time.

How it works

You add the v-once directive to an HTML element in your Vue template. It takes no arguments. On the initial render, Vue processes the element and its children as usual. However, it marks this part of the virtual DOM as static. On subsequent re-renders of the component, Vue's diffing algorithm sees this static marker and skips checking this entire tree for changes, saving CPU cycles.

When to use it

Use v-once for performance optimization on parts of your UI that are expensive to render and never change. This is common for things like displaying a user's name and sign-up date, rendering a large, static list of terms and conditions, or showing a complex SVG icon that is generated but never updated.

When not to use it

Avoid v-once on any element or component that needs to react to data changes. If you place it on a parent element, be aware that you are disabling updates for all its children, which can lead to confusing bugs where the UI doesn't update as expected. Don't use it prematurely; apply it only when you've identified a genuine performance bottleneck.

One canonical example

Imagine you have a component that displays a message that can be updated. If you apply v-once to the element displaying the message, it will show the initial value and never change, even if the underlying message data is modified later. For example: Initial message: {{ message }}. If message starts as "Hello" and is later changed to "Goodbye", the paragraph will always display "Initial message: Hello".