Fix: Props Default Key Has No Corresponding Declaration in Vue.js

What Causes This Warning?

This warning occurs when you provide a default value for a prop that hasn’t been declared. The default key must match an existing prop declaration.

The Problem

// ❌ Default for undeclared prop
export default {
  props: {
    name: String
  },
  // 'age' is not declared in props!
  propsDefaults: {
    age: 25
  }
}

<script setup>
// ❌ withDefaults for undeclared prop
const props = withDefaults(defineProps<{
  name: string
}>(), {
  name: 'John',
  age: 25  // 'age' not in type definition!
})
</script>

The Fix

Declare the Prop

<script setup>
// ✅ All defaults match declarations
const props = withDefaults(defineProps<{
  name: string
  age: number  // Declare the prop
}>(), {
  name: 'John',
  age: 25
})
</script>

Remove Unused Default

<script setup>
// ✅ Only provide defaults for declared props
const props = withDefaults(defineProps<{
  name: string
}>(), {
  name: 'John'
  // Removed 'age' default
})
</script>

Common Scenarios

Options API

// ❌ Typo in default key
export default {
  props: {
    userName: String
  },
  defaults: {
    username: 'Guest' // Typo: should be 'userName'
  }
}

// ✅ Matching keys
export default {
  props: {
    userName: {
      type: String,
      default: 'Guest'
    }
  }
}

TypeScript with defineProps

<script setup lang="ts">
interface Props {
  title: string
  count?: number
}

// ❌ 'items' not in Props
const props = withDefaults(defineProps<Props>(), {
  title: 'Default',
  count: 0,
  items: []  // Not declared!
})

// ✅ All defaults match interface
interface Props {
  title: string
  count?: number
  items?: string[]  // Add to interface
}

const props = withDefaults(defineProps<Props>(), {
  title: 'Default',
  count: 0,
  items: () => []
})
</script>

Refactoring Props

<script setup>
// After removing a prop, also remove its default

// ❌ 'deprecated' prop removed but default remains
const props = withDefaults(defineProps<{
  name: string
}>(), {
  name: 'John',
  deprecated: true  // Prop was removed!
})

// ✅ Clean up defaults when removing props
const props = withDefaults(defineProps<{
  name: string
}>(), {
  name: 'John'
})
</script>

Inline Defaults with Object Syntax

// ✅ Defaults inline with declarations
export default {
  props: {
    name: {
      type: String,
      default: 'Guest'
    },
    items: {
      type: Array,
      default: () => []
    },
    config: {
      type: Object,
      default: () => ({ theme: 'light' })
    }
  }
}

Array Syntax (No Defaults Supported)

// Array syntax doesn't support defaults
export default {
  props: ['name', 'age']
  // Can't add defaults with array syntax
}

// ✅ Convert to object syntax for defaults
export default {
  props: {
    name: {
      type: String,
      default: 'Guest'
    },
    age: {
      type: Number,
      default: 0
    }
  }
}

Quick Checklist

• Every default key must match a declared prop
• Check for typos in prop/default names
• Remove defaults when removing props
• Use object syntax (not array) for defaults
• With TypeScript, ensure interface includes all props with defaults