You’re browsing the documentation for v2.x and earlier. For v3.x, click here. This is the official style guide for Vue-specific code. If you use Vue in a project, it’s a great reference to avoid errors, bikeshedding, and anti-patterns.
However, we don’t believe that any style guide is ideal for all teams or projects, so mindful deviations are encouraged based on past experience, the surrounding tech stack, and personal values.
Styling Vue components with CSS
We don’t mind whether your HTML uses single-quotes or double-quotes for attribute values. Some exceptions will exist however, where we’ve found that a particular pattern is helpful in the context of Vue. Soon, we’ll also provide tips for enforcement.
Sometimes you’ll simply have to be disciplined, but wherever possible, we’ll try to show you how to use ESLint and other automated processes to make enforcement simpler.
Finally, we’ve split rules into four categories:.
These rules help prevent errors, so learn and abide by them at all costs.
Priority A Rules: Essential (Error Prevention)
These rules have been found to improve readability and/or developer experience in most projects.
Your code will still run if you violate them, but violations should be rare and well-justified.
- Where multiple, equally good options exist, an arbitrary choice can be made to ensure consistency.
- In these rules, we describe each acceptable option and suggest a default choice.
- That means you can feel free to make a different choice in your own codebase, as long as you’re consistent and have a good reason.
Please do have a good reason though!
By adapting to the community standard, you will:.
train your brain to more easily parse most of the community code you encounter. be able to copy and paste most community code examples without modification. often find new hires are already accustomed to your preferred coding style, at least in regards to Vue.
Some features of Vue exist to accommodate rare edge cases or smoother migrations from a legacy code base.
When overused however, they can make your code more difficult to maintain or even become a source of bugs. These rules shine a light on potentially risky features, describing when and why they should be avoided. Component names should always be multi-word, except for root App components, and built-in components provided by Vue, such as
This prevents conflicts with existing and future HTML elements, since all HTML elements are a single word. Component data must be a function. When using the data property on a component (i.e.
anywhere except on new Vue), the value must be a function that returns an object.
When the value of data is an object, it’s shared across all instances of a component.
Imagine, for example, a TodoList component with this data:. We might want to reuse this component, allowing users to maintain multiple lists (e.g. for shopping, wishlists, daily chores, etc). There’s a problem though.
Adding global styles to Single File Components
Prop definitions should be as detailed as possible. In committed code, prop definitions should always be as detailed as possible, specifying at least type(s).
Detailed prop definitions have two advantages:. They document the API of the component, so that it’s easy to see how the component is meant to be used. In development, Vue will warn you if a component is ever provided incorrectly formatted props, helping you catch potential sources of error.
Priority D Rules: Use with Caution (Potentially Dangerous Patterns)
Always use key with v-for. key with v-for is always required on components, in order to maintain internal component state down the subtree.
Even for elements though, it’s a good practice to maintain predictable behavior, such as object constancy in animations.
Let’s say you have a list of todos:. Then you sort them alphabetically. When updating the DOM, Vue will optimize rendering to perform the cheapest DOM mutations possible.
That might mean deleting the first todo element, then adding it again at the end of the list.
Adding scoped styles
The problem is, there are cases where it’s important not to delete elements that will remain in the DOM. For example, you may want to use
In these cases, adding a unique key for each item (e.g. :key="todo.id") will tell Vue how to behave more predictably.
In our experience, it’s better to always add a unique key, so that you and your team simply never have to worry about these edge cases. Then in the rare, performance-critical scenarios where object constancy isn’t necessary, you can make a conscious exception.
Never use v-if on the same element as v-for. There are two common cases where this can be tempting:. To filter items in a list (e.g. v-for="user in users" v-if="user.isActive"). In these cases, replace users with a new computed property that returns your filtered list (e.g.
To avoid rendering a list if it should be hidden (e.g. v-for="user in users" v-if="shouldShowUsers"). In these cases, move the v-if to a container element (e.g.
In this module
When Vue processes directives, v-for has a higher priority than v-if, so that this template:. Will be evaluated similar to:. So even if we only render elements for a small fraction of users, we have to iterate over the entire list every time we re-render, whether or not the set of active users has changed.
Priority C Rules: Recommended (Minimizing Arbitrary Choices and Cognitive Overhead)Debugging Vue.js applications can be difficult, especially when there are dozens, if not hundreds of mutations during a user session. If you’re interested in monitoring and tracking Vue mutations for all of your users in production, try LogRocket. https://logrocket.com/signup/
The LogRocket Vuex plugin logs Vuex mutations to the LogRocket console, giving you context around what led to an error, and what state the application was in when an issue occurred.
Modernize how you debug your Vue apps - Start monitoring for free.