✏️Vue 3 `defineProps`와 `withDefaults` (Vue 2와 차이점)

Vue3에서 <script setup> 구문을 사용할 때, 컴포넌트 props를 정의하는 방식이 완전히 달라졌습니다.
이 글에서는 Vue3의 defineProps와 withDefaults 사용법을 예제와 함께 설명하고, Vue2 방식과의 차이점도 짚어보겠습니다.

---

✅ Vue2에서 Props 기본값 설정 방법

Vue2에서는 props를 props 옵션으로 정의하고, 객체 형태로 기본값과 타입을 지정

• default : 기본값 지정
• required : false: 생략 가능 (기본이 false)

export default {
  props: {
    title: {
      type: String,
      required: false,
      default: '상품 이미지'
    },
    itemName: String,
    itemCode: String
  }
}

✅ Vue3: <script Setup>에서의 Props 정의

1. defineProps로 Props 선언

• 타입 기반으로 선언하며, 이때는 기본값 설정이 되지 않습니다.

<script setup>
const props = defineProps<{
  title?: string;
  itemName?: string;
  itemImageList?: any[];
  itemCode?: string;
}>();
</script>

2. withDefaults()로 기본값 지정

• withDefaults는 타입 기반 defineProps에만 사용 가능
• 런타임에 작동하는 유일한 기본값 지정 방법

<script setup>
export interface Props {
  title?: string;
  itemName: string;
  itemImageList: Array<any>;
  itemCode: string;
}
let props = withDefaults(defineProps<Props>(), {
  title: "상품 이미지"
});
</script>

❗vue 3.4 이하 버전에서 타입 기반 선언 시 기본값을 사용시 해당 컴파일러 매크로를 사용하세요 :)
3.5이상의 버전에서만 Reactive Props 구조 분해가 기본 활성화되어
타입기반 definePops 에서도 기본값 설정이 자연스럽게 동작합니다.

🙅‍♀️잘못된 예시 (작동하지 않음)

• Vue2 스타일의 default는 <script setup>에서 무시됨!

// default 속성은 무시됨
const props = defineProps({
  title: {
    type: String,
    default: '상품 이미지'
  }
});

---

🆚 Vue 2 vs Vue 3 차이 요약

항목	Vue 2 (Options API)	Vue 3 (<script setup>)
props 선언	props: { ... }	defineProps 사용
기본값 지정	default: 'value'	withDefaults() 사용
타입 지정	type: String 등	TypeScript 기반 정의 권장
작동 시점	런타임	컴파일 타임 매크로 (defineProps)

---

참고

• Vue 공식 문서 - Props 정의
• Vue 공식 문서 - <script setup> defineProps문법
• Vue 공식 문서 - withDefaults