```
- - Use only valid, non-abstract [ARIA roles](https://www.w3.org/TR/wai-aria/roles#role_definitions). eslint: [`jsx-a11y/aria-role`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-role.md)
+ - Use only valid, non-abstract [ARIA roles](https://www.w3.org/TR/wai-aria/#usage_intro). eslint: [`jsx-a11y/aria-role`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-role.md)
```jsx
// bad - not an ARIA role
@@ -324,7 +352,11 @@
```
- - Avoid using an array index as `key` prop, prefer a unique ID. ([why?](https://medium.com/@robinpokorny/index-as-a-key-is-an-anti-pattern-e0349aece318))
+ - Avoid using an array index as `key` prop, prefer a stable ID. eslint: [`react/no-array-index-key`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-array-index-key.md)
+
+> Why? Not using a stable ID [is an anti-pattern](https://medium.com/@robinpokorny/index-as-a-key-is-an-anti-pattern-e0349aece318) because it can negatively impact performance and cause issues with component state.
+
+We don’t recommend using indexes for keys if the order of items may change.
```jsx
// bad
@@ -374,6 +406,58 @@
};
```
+ - Use spread props sparingly.
+ > Why? Otherwise you’re more likely to pass unnecessary props down to components. And for React v15.6.1 and older, you could [pass invalid HTML attributes to the DOM](https://reactjs.org/blog/2017/09/08/dom-attributes-in-react-16.html).
+
+ Exceptions:
+
+ - HOCs that proxy down props and hoist propTypes
+
+ ```jsx
+ function HOC(WrappedComponent) {
+ return class Proxy extends React.Component {
+ Proxy.propTypes = {
+ text: PropTypes.string,
+ isLoading: PropTypes.bool
+ };
+
+ render() {
+ return -
+
- + {{ todo.text }} + +
-
+
- + {{ todo.text }} + +
-
+
- + {{ user.name }} + +
-
+
- + {{ user.name }} + +
-
+
- + {{ user.name }} + +
-
+
- + {{ user.name }} + +
-
+
- + {{ user.name }} + +
-
+
- + {{ user.name }} + +
-
+
- + {{ user.name }} + +
-
+
- + {{ user.name }} + +
+```
+
+```html
+
+```
+
+```html
+Here might be a page title
+ + + +Here's some contact info
+ +``` + +#### Good + +```html + +``` + +```html + +``` + +```html + +``` + +```html + +``` + +```html + +Here might be a page title
+ + + +Here's some contact info
+ +``` + +```html + +Here might be a page title
+ + + +Here's some contact info
+ +``` + + +## 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. + +1. **Side Effects** (triggers effects outside the component) + - `el` + +2. **Global Awareness** (requires knowledge beyond the component) + - `name` + - `parent` + +3. **Component Type** (changes the type of the component) + - `functional` + +4. **Template Modifiers** (changes the way templates are compiled) + - `delimiters` + - `comments` + +5. **Template Dependencies** (assets used in the template) + - `components` + - `directives` + - `filters` + +6. **Composition** (merges properties into the options) + - `extends` + - `mixins` + +7. **Interface** (the interface to the component) + - `inheritAttrs` + - `model` + - `props`/`propsData` + +8. **Local State** (local reactive properties) + - `data` + - `computed` + +9. **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` + +10. **Non-Reactive Properties** (instance properties independent of the reactivity system) + - `methods` + +11. **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. + +1. **Definition** (provides the component options) + - `is` + +2. **List Rendering** (creates multiple variations of the same element) + - `v-for` + +3. **Conditionals** (whether the element is rendered/shown) + - `v-if` + - `v-else-if` + - `v-else` + - `v-show` + - `v-cloak` + +4. **Render Modifiers** (changes the way the element renders) + - `v-pre` + - `v-once` + +5. **Global Awareness** (requires knowledge beyond the component) + - `id` + +6. **Unique Attributes** (attributes that require unique values) + - `ref` + - `key` + - `slot` + +7. **Two-Way Binding** (combining binding and events) + - `v-model` + +8. **Other Attributes** (all unspecified bound & unbound attributes) + +9. **Events** (component event listeners) + - `v-on` + +10. **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 + +```js +props: { + value: { + type: String, + required: true + }, + + focused: { + type: Boolean, + default: false + }, + + label: String, + icon: String +}, + +computed: { + formattedValue: function () { + // ... + }, + + inputClasses: function () { + // ... + } +} +``` + +```js +// 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](../guide/single-file-components.html) should always order ` +... +``` + +```html + + +... + + + +... + + +``` + +#### Good + +```html + + +... + + + + +... + +``` + +```html + +... + + + + +... + + +``` + + + +## 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 use `key` with `v-if` + `v-else`, if they are the same element type (e.g. both `` 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 have [unintended consequences](https://jsfiddle.net/chrisvfritz/bh8fLeds/) if these elements should not actually be considered the same.
+
+#### Bad
+
+```html
+
+ Error: {{ error }}
+
+
+ {{ results }}
+
+```
+
+#### Good
+
+``` html
+
+ Error: {{ error }}
+
+
+ {{ results }}
+
+```
+
+
+### Element selectors with `scoped` (use with caution)
+
+**Element selectors should be avoided with `scoped`.**
+
+Prefer class selectors over element selectors in `scoped` styles, because large numbers of element selectors are slow.
+
+To scope styles, Vue adds a unique attribute to component elements, such as `data-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](http://stevesouders.com/efws/css-selectors/csscreate.php?n=1000&sel=a%5Bhref%5D&body=background%3A+%23CFD&ne=1000) (e.g. `button[data-v-f3f3eg9]`) will be considerably slower than [class-attribute selectors](http://stevesouders.com/efws/css-selectors/csscreate.php?n=1000&sel=.class%5Bhref%5D&body=background%3A+%23CFD&ne=1000) (e.g. `.btn-close[data-v-f3f3eg9]`), so class selectors should be preferred whenever possible.
+
+#### Bad
+
+```html
+
+
+
+
+
+```
+
+#### Good
+
+```html
+
+
+
+
+
+```
+
+
+### Implicit parent-child communication (use with caution)
+
+**Props and events should be preferred for parent-child component communication, instead of `this.$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 or `this.$parent` can simplify two components that are already deeply coupled.
+
+The problem is, there are also many _simple_ 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
+
+```js
+Vue.component('TodoItem', {
+ props: {
+ todo: {
+ type: Object,
+ required: true
+ }
+ },
+ template: ''
+})
+```
+
+```js
+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: `
+
+ {{ todo.text }}
+
+
+ `
+})
+```
+
+#### Good
+
+```js
+Vue.component('TodoItem', {
+ props: {
+ todo: {
+ type: Object,
+ required: true
+ }
+ },
+ template: `
+
+ `
+})
+```
+
+```js
+Vue.component('TodoItem', {
+ props: {
+ todo: {
+ type: Object,
+ required: true
+ }
+ },
+ template: `
+
+ {{ todo.text }}
+
+
+ `
+})
+```
+
+
+
+### Non-flux state management (use with caution)
+
+**[Vuex](https://github.com/vuejs/vuex) should be preferred for global state management, instead of `this.$root` or a global event bus.**
+
+Managing state on `this.$root` and/or using a [global event bus](https://vuejs.org/v2/guide/migration.html#dispatch-and-broadcast-replaced) can be convenient for very simple cases, but are not appropriate for most applications. Vuex offers not only a central place to manage state, but also tools for organizing, tracking, and debugging state changes.
+
+#### Bad
+
+```js
+// main.js
+new Vue({
+ 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
+
+```js
+// store/modules/todos.js
+export default {
+ 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)
+ }
+ }
+}
+```
+
+```html
+
+
+
+ {{ todo.text }}
+
+
+
+
+
+```
+
+```html
+
+```
+
+## References
+
+- [Style Source: VueJs.org](https://github.com/vuejs/vuejs.org/blob/master/src/v2/style-guide/index.md)