Priority A Rules: 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.

Use multi-word component names ​

User component names should always be multi-word, except for root App components. This prevents conflicts with existing and future HTML elements, since all HTML elements are a single word.

<!-- in pre-compiled templates -->
<Item />

<!-- in in-DOM templates -->
<item></item>

<!-- in pre-compiled templates -->
<TodoItem />

<!-- in in-DOM templates -->
<todo-item></todo-item>

Use detailed prop definitions ​

In committed code, props should be treated as a key part of the component's contract and be defined in as much detail as possible.

In TypeScript, a type-based defineProps() declaration can also be used when the prop contract is fully described by its types.

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

props: {
  status: String
}

// Even better!
props: {
  status: {
    type: String,
    required: true,

    validator: value => {
      return [
        'syncing',
        'synced',
        'version-conflict',
        'error'
      ].includes(value)
    }
  }
}

// This is only OK when prototyping
const props = defineProps(['status'])

const props = defineProps({
  status: String
})

// Even better!
const props = defineProps({
  status: {
    type: String,
    required: true,

    validator: (value) => {
      return ['syncing', 'synced', 'version-conflict', 'error'].includes(
        value
      )
    }
  }
})

Declare emitted events ​

Treat emitted events as part of a component's public contract, and declare them explicitly.

In Options API, declare events with the emits option. In <script setup>, declare them with defineEmits().

Use the object syntax when event payloads need validation, and an array of event names when they do not.

In TypeScript, a typed defineEmits() declaration can also be used so the event contract is checked by the type system as well as documented in the component. Vue 3.3+ also supports a named tuple syntax for the same declaration.

export default {
  methods: {
    submit(email) {
      this.$emit('submit', { email })
    }
  }
}

export default {
  emits: {
    submit: (payload) => typeof payload?.email === 'string'
  },

  methods: {
    submit(email) {
      this.$emit('submit', { email })
    }
  }
}

<template>
  <button @click="$emit('submit')">Submit</button>
</template>

<script setup>
defineEmits(['submit'])
</script>

<template>
  <button @click="$emit('submit')">Submit</button>
</template>

<script setup lang="ts">
const form = {
  email: ''
}

const emit = defineEmits<{
  // Type-based declaration
  (e: 'submit', payload: { email: string }): void
  // Vue 3.3+: alternative, more succinct syntax
  // submit: [payload: { email: string }]
}>()
</script>

<template>
  <button @click="emit('submit', { email: form.email })">Submit</button>
</template>

Keep parent-child data flow explicit ​

Pass data down with props, and communicate requested changes back up with emitted events.

This includes v-model, which still follows the same prop-and-event communication pattern with shorthand syntax.

If a child needs editable local state, derive or initialize it from the prop instead of mutating the prop itself.

export default {
  props: {
    open: Boolean
  },

  methods: {
    requestClose() {
      this.open = false
    }
  }
}

export default {
  props: {
    open: Boolean
  },

  emits: ['update:open'],

  methods: {
    requestClose() {
      this.$emit('update:open', false)
    }
  }
}

const props = defineProps({
  open: Boolean
})

function requestClose() {
  props.open = false
}

const props = defineProps({
  open: Boolean
})

const emit = defineEmits(['update:open'])

function requestClose() {
  emit('update:open', false)
}

Use component-scoped styling ​

Keep component styles within the component boundary unless a style is intentionally global.

<template>
  <button class="btn btn-close">×</button>
</template>

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

<template>
  <button class="button button-close">×</button>
</template>

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

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

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

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

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

Notes

• The scoped attribute is not the only option. CSS modules, native CSS @scope, and disciplined class-based conventions such as BEM can all work.
• App-level and layout-level styles may be global when they are intentionally shared.

Use computed for derived state ​

Use computed for synchronous derived state instead of storing and synchronizing it manually, and use watch, watchEffect(), or lifecycle hooks for side effects.

export default {
  computed: {
    fullName() {
      const value = `${this.user.firstName} ${this.user.lastName}`
      analytics.track('full-name-changed', value)
      return value
    }
  }
}

export default {
  computed: {
    fullName() {
      return `${this.user.firstName} ${this.user.lastName}`
    }
  },

  watch: {
    fullName(value) {
      analytics.track('full-name-changed', value)
    }
  }
}

const fullName = computed(() => {
  const value = `${user.value.firstName} ${user.value.lastName}`
  analytics.track('full-name-changed', value)
  return value
})

const fullName = computed(() => {
  return `${user.value.firstName} ${user.value.lastName}`
})

watch(fullName, (value) => {
  analytics.track('full-name-changed', value)
})