useVueConsistentEventHyphenation (HTML)

Language HTML

Caution

This rule is part of the nursery group. This means that it is experimental and the behavior can change at any time.

Summary

• Rule available since: v2.6.0
• Diagnostic Category: lint/nursery/useVueConsistentEventHyphenation
• This rule has an unsafe fix.
• The default severity of this rule is information.
• This rule belongs to the following domains:
  • vue
• Sources:
  • Same as vue/v-on-event-hyphenation

How to configure

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useVueConsistentEventHyphenation": "error"
      }
    }
  }
}

Description

Enforce a consistent hyphenation style for event names in v-on directives on custom components.

Vue converts event names between camelCase and kebab-case automatically, so @custom-event and @customEvent both listen to an event emitted as customEvent. Mixing both styles makes templates harder to read and search. The Vue documentation recommends kebab-cased event listeners in templates.

The rule only checks components, such as <MyComponent>, <my-component> and <Foo.Bar>. Native elements such as <div> are ignored, even when they have an is attribute. Dynamic event names, such as @[event], are ignored as well.

The fix is unsafe: Vue doesn’t convert event names on custom elements (web components) declared with isCustomElement, so renaming their event listeners can stop them from receiving events.

Examples

Invalid

<template>
  <MyComponent @customEvent="handleEvent" />
</template>

code-block.vue:2:17 lint/nursery/useVueConsistentEventHyphenation  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The event name customEvent isn't hyphenated.
  
    1 │ <template>
  > 2 │   <MyComponent @customEvent="handleEvent" />
      │                 ^^^^^^^^^^^
    3 │ </template>
    4 │ 
  
  ℹ Vue matches event listeners regardless of their casing, so mixing camelCase and kebab-case event names makes templates inconsistent.
  
  ℹ This project requires hyphenated (kebab-case) event names.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Rename the event to custom-event.
  
    1 1 │   <template>
    2   │ - ··<MyComponent·@customEvent="handleEvent"·/>
      2 │ + ··<MyComponent·@custom-event="handleEvent"·/>
    3 3 │   </template>
    4 4 │   
  

<template>
  <MyComponent v-on:update:modelValue="handleEvent" />
</template>

code-block.vue:2:21 lint/nursery/useVueConsistentEventHyphenation  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The event name update:modelValue isn't hyphenated.
  
    1 │ <template>
  > 2 │   <MyComponent v-on:update:modelValue="handleEvent" />
      │                     ^^^^^^^^^^^^^^^^^
    3 │ </template>
    4 │ 
  
  ℹ Vue matches event listeners regardless of their casing, so mixing camelCase and kebab-case event names makes templates inconsistent.
  
  ℹ This project requires hyphenated (kebab-case) event names.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Rename the event to update:model-value.
  
    1 1 │   <template>
    2   │ - ··<MyComponent·v-on:update:modelValue="handleEvent"·/>
      2 │ + ··<MyComponent·v-on:update:model-value="handleEvent"·/>
    3 3 │   </template>
    4 4 │   
  

Valid

<template>
  <MyComponent @custom-event="handleEvent" />
  <MyComponent v-on:update:model-value="handleEvent" />
  <div @customEvent="handleEvent" />
</template>

Options

hyphenation

Whether event names must be hyphenated ("always") or must not contain hyphens ("never").

Default: "always"

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useVueConsistentEventHyphenation": {
          "level": "on",
          "options": {
            "hyphenation": "never"
          }
        }
      }
    }
  }
}

Invalid

<template>
  <MyComponent @custom-event="handleEvent" />
</template>

code-block.vue:2:17 lint/nursery/useVueConsistentEventHyphenation  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The event name custom-event contains hyphens.
  
    1 │ <template>
  > 2 │   <MyComponent @custom-event="handleEvent" />
      │                 ^^^^^^^^^^^^
    3 │ </template>
    4 │ 
  
  ℹ Vue matches event listeners regardless of their casing, so mixing camelCase and kebab-case event names makes templates inconsistent.
  
  ℹ This project requires event names without hyphens, such as camelCase.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Rename the event to customEvent.
  
    1 1 │   <template>
    2   │ - ··<MyComponent·@custom-event="handleEvent"·/>
      2 │ + ··<MyComponent·@customEvent="handleEvent"·/>
    3 3 │   </template>
    4 4 │   
  

Valid

<template>
  <MyComponent @customEvent="handleEvent" />
</template>

ignore

A list of event names that aren’t checked.

Default: []

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useVueConsistentEventHyphenation": {
          "level": "on",
          "options": {
            "ignore": [
              "customEvent"
            ]
          }
        }
      }
    }
  }
}

Valid

<template>
  <MyComponent @customEvent="handleEvent" />
</template>

ignoreTags

A list of tag names whose events aren’t checked. Tag names are matched exactly.

Default: []

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useVueConsistentEventHyphenation": {
          "level": "on",
          "options": {
            "ignoreTags": [
              "MyComponent"
            ]
          }
        }
      }
    }
  }
}

Valid

<template>
  <MyComponent @customEvent="handleEvent" />
</template>

Related links

• Disable a rule
• Configure the code fix
• Rule options
• Source Code (Edit this Page)
• Test Cases
• Try in the playground