Special Sponsor

Platinum Sponsors

Become a Sponsor

Style Guide^beta

Platinum Sponsors

Become a Sponsor

Style Guide

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.

For the most part, we also avoid suggestions about JavaScript or HTML in general. We don’t mind whether you use semicolons or trailing commas. 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:

Rule Categories

Priority A: Essential

These rules help prevent errors, so learn and abide by them at all costs. Exceptions may exist, but should be very rare and only be made by those with expert knowledge of both JavaScript and Vue.

Priority B: Strongly Recommended

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.

Priority C: Recommended

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

Priority D: Use with Caution

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.

Priority A Rules: Essential (Error Prevention)

Multi-word component names^essential

Component names should always be multi-word, except for rootApp components, and built-in components provided by Vue, such as<transition> or<component>.

Thisprevents conflicts with existing and future HTML elements, since all HTML elements are a single word.

Bad

Vue.component('todo', {
// ...
})

exportdefault {
name:'Todo',
// ...
}

Good

Vue.component('todo-item', {
// ...
})

exportdefault {
name:'TodoItem',
// ...
}

Component data^essential

Componentdata must be a function.

When using thedata property on a component (i.e. anywhere except onnew Vue), the value must be a function that returns an object.

Detailed Explanation

When the value ofdata is an object, it’s shared across all instances of a component. Imagine, for example, aTodoList component with this data:

data: {
listTitle:'',
todos: []
}

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. Since every instance of the component references the same data object, changing the title of one list will also change the title of every other list. The same is true for adding/editing/deleting a todo.

Instead, we want each component instance to only manage its own data. For that to happen, each instance must generate a unique data object. In JavaScript, this can be accomplished by returning the object in a function:

data:function () {
return {
listTitle:'',
todos: []
  }
}

Bad

Vue.component('some-comp', {
data: {
foo:'bar'
  }
})

exportdefault {
data: {
foo:'bar'
  }
}

Good

Vue.component('some-comp', {
data:function () {
return {
foo:'bar'
    }
  }
})

// In a .vue file
exportdefault {
  data () {
return {
foo:'bar'
    }
  }
}

// It's OK to use an object directly in a root
// Vue instance, since only a single instance
// will ever exist.
newVue({
data: {
foo:'bar'
  }
})

Prop definitions^essential

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 Explanation

Detailedprop 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.

Bad

// This is only OK when prototyping
props: ['status']

Good

props: {
status:String
}

// Even better!
props: {
status: {
type:String,
required:true,
validator:function (value) {
return [
'syncing',
'synced',
'version-conflict',
'error'
      ].indexOf(value) !== -1
    }
  }
}

Keyed`v-for`^essential

Always usekey withv-for.

key withv-for isalways 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 asobject constancy in animations.

Detailed Explanation

Let’s say you have a list of todos:

data:function () {
return {
todos: [
      {
id:1,
text:'Learn to use v-for'
      },
      {
id:2,
text:'Learn to use key'
      }
    ]
  }
}

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.

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<transition-group> to animate list sorting, or maintain focus if the rendered element is an<input>. 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 toalways 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.

Bad

<ul>
<liv-for="todo in todos">
    {{ todo.text }}
</li>
</ul>

Good

<ul>
<li
v-for="todo in todos"
:key="todo.id"
  >
    {{ todo.text }}
</li>
</ul>

Avoid`v-if` with`v-for`^essential

Never usev-if on the same element asv-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, replaceusers with a new computed property that returns your filtered list (e.g.activeUsers).
To avoid rendering a list if it should be hidden (e.g.v-for="user in users" v-if="shouldShowUsers"). In these cases, move thev-if to a container element (e.g.ul,ol).

Detailed Explanation

When Vue processes directives,v-for has a higher priority thanv-if, so that this template:

<ul>
<li
v-for="user in users"
v-if="user.isActive"
:key="user.id"
  >
    {{ user.name }}
</li>
</ul>

Will be evaluated similar to:

this.users.map(function (user) {
if (user.isActive) {
return user.name
  }
})

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.

By iterating over a computed property instead, like this:

computed: {
activeUsers:function () {
returnthis.users.filter(function (user) {
return user.isActive
    })
  }
}

<ul>
<li
v-for="user in activeUsers"
:key="user.id"
  >
    {{ user.name }}
</li>
</ul>

We get the following benefits:

The filtered list willonly be re-evaluated if there are relevant changes to theusers array, making filtering much more efficient.
Usingv-for="user in activeUsers", weonly iterate over active users during render, making rendering much more efficient.
Logic is now decoupled from the presentation layer, making maintenance (change/extension of logic) much easier.

We get similar benefits from updating:

<ul>
<li
v-for="user in users"
v-if="shouldShowUsers"
:key="user.id"
  >
    {{ user.name }}
</li>
</ul>

to:

<ulv-if="shouldShowUsers">
<li
v-for="user in users"
:key="user.id"
  >
    {{ user.name }}
</li>
</ul>

By moving thev-if to a container element, we’re no longer checkingshouldShowUsers forevery user in the list. Instead, we check it once and don’t even evaluate thev-for ifshouldShowUsers is false.

Bad

<ul>
<li
v-for="user in users"
v-if="user.isActive"
:key="user.id"
  >
    {{ user.name }}
</li>
</ul>

<ul>
<li
v-for="user in users"
v-if="shouldShowUsers"
:key="user.id"
  >
    {{ user.name }}
</li>
</ul>

Good

<ul>
<li
v-for="user in activeUsers"
:key="user.id"
  >
    {{ user.name }}
</li>
</ul>

<ulv-if="shouldShowUsers">
<li
v-for="user in users"
:key="user.id"
  >
    {{ user.name }}
</li>
</ul>

Component style scoping^essential

For applications, styles in a top-levelApp component and in layout components may be global, but all other components should always be scoped.

This is only relevant forsingle-file components. It doesnot require that thescoped attribute be used. Scoping could be throughCSS modules, a class-based strategy such asBEM, or another library/convention.

Component libraries, however, should prefer a class-based strategy instead of using thescoped attribute.

This makes overriding internal styles easier, with human-readable class names that don’t have too high specificity, but are still very unlikely to result in a conflict.

Detailed Explanation

If you are developing a large project, working with other developers, or sometimes include 3rd-party HTML/CSS (e.g. from Auth0), consistent scoping will ensure that your styles only apply to the components they are meant for.

Beyond thescoped attribute, using unique class names can help ensure that 3rd-party CSS does not apply to your own HTML. For example, many projects use thebutton,btn, oricon class names, so even if not using a strategy such as BEM, adding an app-specific and/or component-specific prefix (e.g.ButtonClose-icon) can provide some protection.

Bad

<template>
<buttonclass="btn btn-close">X</button>
</template>

<style>
.btn-close {
background-color: red;
}
</style>

Good

<template>
<buttonclass="button button-close">X</button>
</template>

<!-- Using the `scoped` attribute -->
<stylescoped>
.button {
border: none;
border-radius:2px;
}

.button-close {
background-color: red;
}
</style>

<template>
<button:class="[$style.button, $style.buttonClose]">X</button>
</template>

<!-- Using CSS modules -->
<stylemodule>
.button {
border: none;
border-radius:2px;
}

.buttonClose {
background-color: red;
}
</style>

<template>
<buttonclass="c-Button c-Button--close">X</button>
</template>

<!-- Using the BEM convention -->
<style>
.c-Button {
border: none;
border-radius:2px;
}

.c-Button--close {
background-color: red;
}
</style>

Private property names^essential

Use module scoping to keep private functions inaccessible from the outside. If that’s not possible, always use the$_ prefix for custom private properties in a plugin, mixin, etc that should not be considered public API. Then to avoid conflicts with code by other authors, also include a named scope (e.g.$_yourPluginName_).

Detailed Explanation

Vue uses the_ prefix to define its own private properties, so using the same prefix (e.g._update) risks overwriting an instance property. Even if you check and Vue is not currently using a particular property name, there is no guarantee a conflict won’t arise in a later version.

As for the$ prefix, its purpose within the Vue ecosystem is special instance properties that are exposed to the user, so using it forprivate properties would not be appropriate.

Instead, we recommend combining the two prefixes into$_, as a convention for user-defined private properties that guarantee no conflicts with Vue.

Bad

var myGreatMixin = {
// ...
methods: {
update:function () {
// ...
    }
  }
}

var myGreatMixin = {
// ...
methods: {
_update:function () {
// ...
    }
  }
}

var myGreatMixin = {
// ...
methods: {
$update:function () {
// ...
    }
  }
}

var myGreatMixin = {
// ...
methods: {
$_update:function () {
// ...
    }
  }
}

Good

var myGreatMixin = {
// ...
methods: {
$_myGreatMixin_update:function () {
// ...
    }
  }
}

// Even better!
var myGreatMixin = {
// ...
methods: {
publicMethod() {
// ...
myPrivateFunction()
    }
  }
}

functionmyPrivateFunction() {
// ...
}

exportdefault myGreatMixin

Priority B Rules: Strongly Recommended (Improving Readability)

Component files^{strongly recommended}

Whenever a build system is available to concatenate files, each component should be in its own file.

This helps you to more quickly find a component when you need to edit it or review how to use it.

Bad

Vue.component('TodoList', {
// ...
})

Vue.component('TodoItem', {
// ...
})

Good

components/
|- TodoList.js
|- TodoItem.js

components/
|- TodoList.vue
|- TodoItem.vue

Single-file component filename casing^{strongly recommended}

Filenames ofsingle-file components should either be always PascalCase or always kebab-case.

PascalCase works best with autocompletion in code editors, as it’s consistent with how we reference components in JS(X) and templates, wherever possible. However, mixed case filenames can sometimes create issues on case-insensitive file systems, which is why kebab-case is also perfectly acceptable.

Bad

components/
|- mycomponent.vue

components/
|- myComponent.vue

Good

components/
|- MyComponent.vue

components/
|- my-component.vue

Base component names^{strongly recommended}

Base components (a.k.a. presentational, dumb, or pure components) that apply app-specific styling and conventions should all begin with a specific prefix, such asBase,App, orV.

Detailed Explanation

These components lay the foundation for consistent styling and behavior in your application. They mayonly contain:

HTML elements,
other base components, and
3rd-party UI components.

But they’llnever contain global state (e.g. from a Vuex store).

Their names often include the name of an element they wrap (e.g.BaseButton,BaseTable), unless no element exists for their specific purpose (e.g.BaseIcon). If you build similar components for a more specific context, they will almost always consume these components (e.g.BaseButton may be used inButtonSubmit).

Some advantages of this convention:

When organized alphabetically in editors, your app’s base components are all listed together, making them easier to identify.
Since component names should always be multi-word, this convention prevents you from having to choose an arbitrary prefix for simple component wrappers (e.g.MyButton,VueButton).

Bad

components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue

Good

components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue

components/
|- AppButton.vue
|- AppTable.vue
|- AppIcon.vue

components/
|- VButton.vue
|- VTable.vue
|- VIcon.vue

Single-instance component names^{strongly recommended}

Components that should only ever have a single active instance should begin with theThe prefix, to denote that there can be only one.

This does not mean the component is only used in a single page, but it will only be used onceper page. These components never accept any props, since they are specific to your app, not their context within your app. If you find the need to add props, it’s a good indication that this is actually a reusable component that is only used once per pagefor now.

Bad

components/
|- Heading.vue
|- MySidebar.vue

Good

components/
|- TheHeading.vue
|- TheSidebar.vue

Tightly coupled component names^{strongly recommended}

Child components that are tightly coupled with their parent should include the parent component name as a prefix.

If a component only makes sense in the context of a single parent component, that relationship should be evident in its name. Since editors typically organize files alphabetically, this also keeps these related files next to each other.

Detailed Explanation

You might be tempted to solve this problem by nesting child components in directories named after their parent. For example:

components/
|- TodoList/
   |- Item/
      |- index.vue
      |- Button.vue
   |- index.vue

or:

components/
|- TodoList/
   |- Item/
      |- Button.vue
   |- Item.vue
|- TodoList.vue

This isn’t recommended, as it results in:

Many files with similar names, making rapid file switching in code editors more difficult.
Many nested sub-directories, which increases the time it takes to browse components in an editor’s sidebar.

Bad

components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue

components/
|- SearchSidebar.vue
|- NavigationForSearchSidebar.vue

Good

components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue

components/
|- SearchSidebar.vue
|- SearchSidebarNavigation.vue

Order of words in component names^{strongly recommended}

Component names should start with the highest-level (often most general) words and end with descriptive modifying words.

Detailed Explanation

You may be wondering:

“Why would we force component names to use less natural language?”

In natural English, adjectives and other descriptors do typically appear before the nouns, while exceptions require connector words. For example:

Coffeewith milk
Soupof the day
Visitorto the museum

You can definitely include these connector words in component names if you’d like, but the order is still important.

Also note thatwhat’s considered “highest-level” will be contextual to your app. For example, imagine an app with a search form. It may include components like this one:

components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue

As you might notice, it’s quite difficult to see which components are specific to the search. Now let’s rename the components according to the rule:

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputExcludeGlob.vue
|- SearchInputQuery.vue
|- SettingsCheckboxLaunchOnStartup.vue
|- SettingsCheckboxTerms.vue

Since editors typically organize files alphabetically, all the important relationships between components are now evident at a glance.

You might be tempted to solve this problem differently, nesting all the search components under a “search” directory, then all the settings components under a “settings” directory. We only recommend considering this approach in very large apps (e.g. 100+ components), for these reasons:

It generally takes more time to navigate through nested sub-directories, than scrolling through a singlecomponents directory.
Name conflicts (e.g. multipleButtonDelete.vue components) make it more difficult to quickly navigate to a specific component in a code editor.
Refactoring becomes more difficult, because find-and-replace often isn’t sufficient to update relative references to a moved component.

Bad

components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue

Good

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue

Self-closing components^{strongly recommended}

Components with no content should be self-closing insingle-file components, string templates, andJSX - but never in DOM templates.

Components that self-close communicate that they not only have no content, but aremeant to have no content. It’s the difference between a blank page in a book and one labeled “This page intentionally left blank.” Your code is also cleaner without the unnecessary closing tag.

Unfortunately, HTML doesn’t allow custom elements to be self-closing - onlyofficial “void” elements. That’s why the strategy is only possible when Vue’s template compiler can reach the template before the DOM, then serve the DOM spec-compliant HTML.

Bad

<!-- In single-file components, string templates, and JSX -->
<MyComponent></MyComponent>

<!-- In DOM templates -->
<my-component/>

Good

<!-- In single-file components, string templates, and JSX -->
<MyComponent/>

<!-- In DOM templates -->
<my-component></my-component>

Component name casing in templates^{strongly recommended}

In most projects, component names should always be PascalCase insingle-file components and string templates - but kebab-case in DOM templates.

PascalCase has a few advantages over kebab-case:

Editors can autocomplete component names in templates, because PascalCase is also used in JavaScript.
<MyComponent> is more visually distinct from a single-word HTML element than<my-component>, because there are two character differences (the two capitals), rather than just one (a hyphen).
If you use any non-Vue custom elements in your templates, such as a web component, PascalCase ensures that your Vue components remain distinctly visible.

Unfortunately, due to HTML’s case insensitivity, DOM templates must still use kebab-case.

Also note that if you’ve already invested heavily in kebab-case, consistency with HTML conventions and being able to use the same casing across all your projects may be more important than the advantages listed above. In those cases,using kebab-case everywhere is also acceptable.

Bad

<!-- In single-file components and string templates -->
<mycomponent/>

<!-- In single-file components and string templates -->
<myComponent/>

<!-- In DOM templates -->
<MyComponent></MyComponent>

Good

<!-- In single-file components and string templates -->
<MyComponent/>

<!-- In DOM templates -->
<my-component></my-component>

<!-- Everywhere -->
<my-component></my-component>

Component name casing in JS/JSX^{strongly recommended}

Component names in JS/JSX should always be PascalCase, though they may be kebab-case inside strings for simpler applications that only use global component registration throughVue.component.

Detailed Explanation

In JavaScript, PascalCase is the convention for classes and prototype constructors - essentially, anything that can have distinct instances. Vue components also have instances, so it makes sense to also use PascalCase. As an added benefit, using PascalCase within JSX (and templates) allows readers of the code to more easily distinguish between components and HTML elements.

However, for applications that useonly global component definitions viaVue.component, we recommend kebab-case instead. The reasons are:

It’s rare that global components are ever referenced in JavaScript, so following a convention for JavaScript makes less sense.
These applications always include many in-DOM templates, wherekebab-casemust be used.

Bad

Vue.component('myComponent', {
// ...
})

import myComponentfrom'./MyComponent.vue'

exportdefault {
name:'myComponent',
// ...
}

exportdefault {
name:'my-component',
// ...
}

Good

Vue.component('MyComponent', {
// ...
})

Vue.component('my-component', {
// ...
})

importMyComponentfrom'./MyComponent.vue'

exportdefault {
name:'MyComponent',
// ...
}

Full-word component names^{strongly recommended}

Component names should prefer full words over abbreviations.

The autocompletion in editors make the cost of writing longer names very low, while the clarity they provide is invaluable. Uncommon abbreviations, in particular, should always be avoided.

Bad

components/
|- SdSettings.vue
|- UProfOpts.vue

Good

components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue

Prop name casing^{strongly recommended}

Prop names should always use camelCase during declaration, but kebab-case in templates andJSX.

We’re simply following the conventions of each language. Within JavaScript, camelCase is more natural. Within HTML, kebab-case is.

Bad

props: {
'greeting-text':String
}

<WelcomeMessagegreetingText="hi"/>

Good

props: {
greetingText:String
}

<WelcomeMessagegreeting-text="hi"/>

Multi-attribute elements^{strongly recommended}

Elements with multiple attributes should span multiple lines, with one attribute per line.

In JavaScript, splitting objects with multiple properties over multiple lines is widely considered a good convention, because it’s much easier to read. Our templates andJSX deserve the same consideration.

Bad

<imgsrc="https://vuejs.org/images/logo.png"alt="Vue Logo">

<MyComponentfoo="a"bar="b"baz="c"/>

Good

<img
src="https://vuejs.org/images/logo.png"
alt="Vue Logo"
>

<MyComponent
foo="a"
bar="b"
baz="c"
/>

Simple expressions in templates^{strongly recommended}

Component templates should only include simple expressions, with more complex expressions refactored into computed properties or methods.

Complex expressions in your templates make them less declarative. We should strive to describewhat should appear, nothow we’re computing that value. Computed properties and methods also allow the code to be reused.

Bad

{{
  fullName.split(' ').map(function (word) {
    return word[0].toUpperCase() + word.slice(1)
  }).join(' ')
}}

Good

<!-- In a template -->
{{ normalizedFullName }}

// The complex expression has been moved to a computed property
computed: {
normalizedFullName:function () {
returnthis.fullName.split(' ').map(function (word) {
return word[0].toUpperCase() + word.slice(1)
    }).join(' ')
  }
}

Simple computed properties^{strongly recommended}

Complex computed properties should be split into as many simpler properties as possible.

Detailed Explanation

Simpler, well-named computed properties are:

Easier to test
When each computed property contains only a very simple expression, with very few dependencies, it’s much easier to write tests confirming that it works correctly.
Easier to read
Simplifying computed properties forces you to give each value a descriptive name, even if it’s not reused. This makes it much easier for other developers (and future you) to focus on the code they care about and figure out what’s going on.
More adaptable to changing requirements
Any value that can be named might be useful to the view. For example, we might decide to display a message telling the user how much money they saved. We might also decide to calculate sales tax, but perhaps display it separately, rather than as part of the final price.
Small, focused computed properties make fewer assumptions about how information will be used, so require less refactoring as requirements change.

Bad

computed: {
price:function () {
var basePrice =this.manufactureCost / (1 -this.profitMargin)
return (
      basePrice -
      basePrice * (this.discountPercent ||0)
    )
  }
}

Good

computed: {
basePrice:function () {
returnthis.manufactureCost / (1 -this.profitMargin)
  },
discount:function () {
returnthis.basePrice * (this.discountPercent ||0)
  },
finalPrice:function () {
returnthis.basePrice -this.discount
  }
}

Quoted attribute values^{strongly recommended}

Non-empty HTML attribute values should always be inside quotes (single or double, whichever is not used in JS).

While attribute values without any spaces are not required to have quotes in HTML, this practice often leads toavoiding spaces, making attribute values less readable.

Bad

<inputtype=text>

<AppSidebar:style={width:sidebarWidth+'px'}>

Good

<inputtype="text">

<AppSidebar:style="{ width: sidebarWidth + 'px' }">

Directive shorthands^{strongly recommended}

Directive shorthands (: forv-bind:,@ forv-on: and# forv-slot) should be used always or never.

Bad

<input
v-bind:value="newTodoText"
:placeholder="newTodoInstructions"
>

<input
v-on:input="onInput"
  @focus="onFocus"
>

<templatev-slot:header>
<h1>Here might be a page title</h1>
</template>

<template #footer>
<p>Here's some contact info</p>
</template>

Good

<input
:value="newTodoText"
:placeholder="newTodoInstructions"
>

<input
v-bind:value="newTodoText"
v-bind:placeholder="newTodoInstructions"
>

<input
  @input="onInput"
  @focus="onFocus"
>

<input
v-on:input="onInput"
v-on:focus="onFocus"
>

<templatev-slot:header>
<h1>Here might be a page title</h1>
</template>

<templatev-slot:footer>
<p>Here's some contact info</p>
</template>

<template #header>
<h1>Here might be a page title</h1>
</template>

<template #footer>
<p>Here's some contact info</p>
</template>

Priority C Rules: Recommended (Minimizing Arbitrary Choices and Cognitive Overhead)

Component/instance options order^recommended

Component/instance options should be ordered consistently.

This is the default order we recommend for component options. They’re split into categories, so you’ll know where to add new properties from plugins.

Side Effects (triggers effects outside the component)
- el
Global Awareness (requires knowledge beyond the component)
- name
- parent
Component Type (changes the type of the component)
- functional
Template Modifiers (changes the way templates are compiled)
- delimiters
- comments
Template Dependencies (assets used in the template)
- components
- directives
- filters
Composition (merges properties into the options)
- extends
- mixins
Interface (the interface to the component)
- inheritAttrs
- model
- props/propsData
Local State (local reactive properties)
- data
- computed
Events (callbacks triggered by reactive events)
- watch
- Lifecycle Events (in the order they are called)
  - beforeCreate
  - created
  - beforeMount
  - mounted
  - beforeUpdate
  - updated
  - activated
  - deactivated
  - beforeDestroy
  - destroyed
Non-Reactive Properties (instance properties independent of the reactivity system)
- methods
Rendering (the declarative description of the component output)
- template/render
- renderError

Element attribute order^recommended

The attributes of elements (including components) should be ordered consistently.

This is the default order we recommend for component options. They’re split into categories, so you’ll know where to add custom attributes and directives.

Definition (provides the component options)
- is
List Rendering (creates multiple variations of the same element)
- v-for
Conditionals (whether the element is rendered/shown)
- v-if
- v-else-if
- v-else
- v-show
- v-cloak
Render Modifiers (changes the way the element renders)
- v-pre
- v-once
Global Awareness (requires knowledge beyond the component)
- id
Unique Attributes (attributes that require unique values)
- ref
- key
Two-Way Binding (combining binding and events)
- v-model
Other Attributes (all unspecified bound & unbound attributes)
Events (component event listeners)
- v-on
Content (overrides the content of the element)
- v-html
- v-text

Empty lines in component/instance options^recommended

You may want to add one empty line between multi-line properties, particularly if the options can no longer fit on your screen without scrolling.

When components begin to feel cramped or difficult to read, adding spaces between multi-line properties can make them easier to skim again. In some editors, such as Vim, formatting options like this can also make them easier to navigate with the keyboard.

Good

props: {
value: {
type:String,
required:true
  },

focused: {
type:Boolean,
default:false
  },

label:String,
icon:String
},

computed: {
formattedValue:function () {
// ...
  },

inputClasses:function () {
// ...
  }
}

// No spaces are also fine, as long as the component
// is still easy to read and navigate.
props: {
value: {
type:String,
required:true
  },
focused: {
type:Boolean,
default:false
  },
label:String,
icon:String
},
computed: {
formattedValue:function () {
// ...
  },
inputClasses:function () {
// ...
  }
}

Single-file component top-level element order^recommended

Single-file components should always order<script>,<template>, and<style> tags consistently, with<style> last, because at least one of the other two is always necessary.

Bad

<style>/* ... */</style>
<script>/* ... */</script>
<template>...</template>

<!-- ComponentA.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>

Good

<!-- ComponentA.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>

<!-- ComponentA.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>

Priority D Rules: Use with Caution (Potentially Dangerous Patterns)

`v-if`/`v-else-if`/`v-else` without`key`^{use with caution}

It’s usually best to usekey withv-if +v-else, if they are the same element type (e.g. both<div> elements).

By default, Vue updates the DOM as efficiently as possible. That means when switching between elements of the same type, it simply patches the existing element, rather than removing it and adding a new one in its place. This can haveunintended consequences if these elements should not actually be considered the same.

Bad

<divv-if="error">
  Error: {{ error }}
</div>
<divv-else>
  {{ results }}
</div>

Good

<div
v-if="error"
key="search-status"
>
  Error: {{ error }}
</div>
<div
v-else
key="search-results"
>
  {{ results }}
</div>

Element selectors with`scoped`^{use with caution}

Element selectors should be avoided withscoped.

Prefer class selectors over element selectors inscoped styles, because large numbers of element selectors are slow.

Detailed Explanation

To scope styles, Vue adds a unique attribute to component elements, such asdata-v-f3f3eg9. Then selectors are modified so that only matching elements with this attribute are selected (e.g.button[data-v-f3f3eg9]).

The problem is that large numbers of element-attribute selectors (e.g.button[data-v-f3f3eg9]) will be considerably slower than class-attribute selectors (e.g..btn-close[data-v-f3f3eg9]), so class selectors should be preferred whenever possible.

Bad

<template>
<button>X</button>
</template>

<stylescoped>
button {
background-color: red;
}
</style>

Good

<template>
<buttonclass="btn btn-close">X</button>
</template>

<stylescoped>
.btn-close {
background-color: red;
}
</style>

Implicit parent-child communication^{use with caution}

Props and events should be preferred for parent-child component communication, instead ofthis.$parent or mutating props.

An ideal Vue application is props down, events up. Sticking to this convention makes your components much easier to understand. However, there are edge cases where prop mutation orthis.$parent can simplify two components that are already deeply coupled.

The problem is, there are also manysimple cases where these patterns may offer convenience. Beware: do not be seduced into trading simplicity (being able to understand the flow of your state) for short-term convenience (writing less code).

Bad

Vue.component('TodoItem', {
props: {
todo: {
type:Object,
required:true
    }
  },
template:'<input v-model="todo.text">'
})

Vue.component('TodoItem', {
props: {
todo: {
type:Object,
required:true
    }
  },
methods: {
    removeTodo () {
var vm =this
      vm.$parent.todos = vm.$parent.todos.filter(function (todo) {
return todo.id !== vm.todo.id
      })
    }
  },
template:`
    <span>
      {{ todo.text }}
      <button @click="removeTodo">
        X
      </button>
    </span>
  `
})

Good

Vue.component('TodoItem', {
props: {
todo: {
type:Object,
required:true
    }
  },
template:`
    <input
      :value="todo.text"
      @input="$emit('input', $event.target.value)"
    >
  `
})

Vue.component('TodoItem', {
props: {
todo: {
type:Object,
required:true
    }
  },
template:`
    <span>
      {{ todo.text }}
      <button @click="$emit('delete')">
        X
      </button>
    </span>
  `
})

Non-flux state management^{use with caution}

Vuex should be preferred for global state management, instead ofthis.$root or a global event bus.

Managing state onthis.$root and/or using aglobal event bus can be convenient for very simple cases, but it is not appropriate for most applications.

Vuex is theofficial flux-like implementation for Vue, and offers not only a central place to manage state, but also tools for organizing, tracking, and debugging state changes. It integrates well in the Vue ecosystem (including fullVue DevTools support).

Bad

// main.js
newVue({
data: {
todos: []
  },
created:function () {
this.$on('remove-todo',this.removeTodo)
  },
methods: {
removeTodo:function (todo) {
var todoIdToRemove = todo.id
this.todos =this.todos.filter(function (todo) {
return todo.id !== todoIdToRemove
      })
    }
  }
})

Good

// store/modules/todos.js
exportdefault {
state: {
list: []
  },
mutations: {
REMOVE_TODO (state, todoId) {
      state.list = state.list.filter(todo => todo.id !== todoId)
    }
  },
actions: {
    removeTodo ({ commit, state }, todo) {
commit('REMOVE_TODO', todo.id)
    }
  }
}

<!-- TodoItem.vue -->
<template>
<span>
    {{ todo.text }}
<button @click="removeTodo(todo)">
      X
</button>
</span>
</template>

<script>
import { mapActions }from'vuex'

exportdefault {
props: {
todo: {
type:Object,
required:true
    }
  },
methods:mapActions(['removeTodo'])
}
</script>

Caught a mistake or want to contribute to the documentation? Edit this on GitHub! Deployed on Netlify.

Movatterモバイル変換

Style Guidebeta

Style Guide

Rule Categories

Priority A: Essential

Priority B: Strongly Recommended

Priority C: Recommended

Priority D: Use with Caution

Priority A Rules: Essential (Error Prevention)

Multi-word component namesessential

Bad

Good

Component dataessential

Detailed Explanation

Bad

Good

Prop definitionsessential

Detailed Explanation

Bad

Good

Keyedv-foressential

Detailed Explanation

Bad

Good

Avoidv-if withv-foressential

Detailed Explanation

Bad

Good

Component style scopingessential

Detailed Explanation

Bad

Good

Private property namesessential

Detailed Explanation

Bad

Good

Priority B Rules: Strongly Recommended (Improving Readability)

Component filesstrongly recommended

Bad

Good

Single-file component filename casingstrongly recommended

Bad

Good

Base component namesstrongly recommended

Detailed Explanation

Bad

Good

Single-instance component namesstrongly recommended

Bad

Good

Tightly coupled component namesstrongly recommended

Detailed Explanation

Bad

Good

Order of words in component namesstrongly recommended

Detailed Explanation

Bad

Good

Self-closing componentsstrongly recommended

Bad

Good

Component name casing in templatesstrongly recommended

Bad

Good

Component name casing in JS/JSXstrongly recommended

Detailed Explanation

Bad

Good

Full-word component namesstrongly recommended

Bad

Good

Prop name casingstrongly recommended

Bad

Good

Multi-attribute elementsstrongly recommended

Bad

Good

Simple expressions in templatesstrongly recommended

Bad

Good

Style Guide^beta

Multi-word component names^essential

Component data^essential

Prop definitions^essential

Keyed`v-for`^essential

Avoid`v-if` with`v-for`^essential

Component style scoping^essential

Private property names^essential

Component files^{strongly recommended}

Single-file component filename casing^{strongly recommended}

Base component names^{strongly recommended}

Single-instance component names^{strongly recommended}

Tightly coupled component names^{strongly recommended}

Order of words in component names^{strongly recommended}

Self-closing components^{strongly recommended}

Component name casing in templates^{strongly recommended}

Component name casing in JS/JSX^{strongly recommended}

Full-word component names^{strongly recommended}

Prop name casing^{strongly recommended}

Multi-attribute elements^{strongly recommended}

Simple expressions in templates^{strongly recommended}

Simple computed properties^{strongly recommended}

Quoted attribute values^{strongly recommended}

Directive shorthands^{strongly recommended}

Component/instance options order^recommended

Element attribute order^recommended

Empty lines in component/instance options^recommended

Single-file component top-level element order^recommended

`v-if`/`v-else-if`/`v-else` without`key`^{use with caution}

Element selectors with`scoped`^{use with caution}

Implicit parent-child communication^{use with caution}

Non-flux state management^{use with caution}