1---
2title: Boolean Props Default to false, Not undefined
3impact: MEDIUM
4impactDescription: TypeScript expects optional boolean to be undefined but Vue defaults it to false, causing type confusion
5type: gotcha
6tags: [vue3, typescript, props, boolean, defineProps]
7---
8 
9# Boolean Props Default to false, Not undefined
10 
11**Impact: MEDIUM** - When using type-based `defineProps`, optional boolean props (marked with `?`) behave differently than TypeScript expects. Vue treats boolean props specially: an absent boolean prop defaults to `false`, not `undefined`. This can cause confusion when TypeScript thinks the type is `boolean | undefined`.
12 
13## Task Checklist
14 
15- [ ] Understand that Vue's boolean casting makes absent booleans `false`
16- [ ] Use `withDefaults()` to be explicit about boolean defaults
17- [ ] Consider using non-boolean types if `undefined` is a meaningful state
18- [ ] Document this Vue-specific behavior for your team
19 
20## The Gotcha
21 
22```vue
23<script setup lang="ts">
24interface Props {
25  disabled?: boolean  // TypeScript sees: boolean | undefined
26}
27 
28const props = defineProps<Props>()
29 
30// TypeScript thinks props.disabled could be undefined
31if (props.disabled === undefined) {
32  console.log('This will NEVER run!')
33  // Vue's boolean casting means disabled is false, not undefined
34}
35</script>
36 
37<template>
38  <!-- When used without the prop -->
39  <MyComponent />
40  <!-- disabled is false, NOT undefined -->
41</template>
42```
43 
44## Why This Happens
45 
46Vue has special "boolean casting" behavior inherited from HTML boolean attributes:
47 
48```vue
49<!-- All of these make disabled = true -->
50<MyComponent disabled />
51<MyComponent :disabled="true" />
52<MyComponent disabled="" />
53 
54<!-- This makes disabled = false (NOT undefined) -->
55<MyComponent />
56 
57<!-- Explicit false -->
58<MyComponent :disabled="false" />
59```
60 
61This is by design to match how HTML works:
62```html
63<!-- HTML: presence means true, absence means false -->
64<button disabled>Can't click</button>
65<button>Can click</button>
66```
67 
68## Solutions
69 
70### Solution 1: Be Explicit with withDefaults
71 
72Make your intention clear:
73 
74```vue
75<script setup lang="ts">
76interface Props {
77  disabled?: boolean
78}
79 
80// Explicitly document the default
81const props = withDefaults(defineProps<Props>(), {
82  disabled: false  // Now it's clear this defaults to false
83})
84</script>
85```
86 
87### Solution 2: Use a Three-State Type
88 
89If you actually need to distinguish "not set" from "explicitly false":
90 
91```vue
92<script setup lang="ts">
93interface Props {
94  // Use a union type instead of optional boolean
95  state?: 'enabled' | 'disabled' | undefined
96 
97  // Or use undefined explicitly
98  toggleState?: boolean | undefined
99}
100 
101const props = withDefaults(defineProps<Props>(), {
102  state: undefined,  // Can actually be undefined
103  toggleState: undefined
104})
105 
106// Now you can check for undefined
107if (props.state === undefined) {
108  // Use parent's state
109} else if (props.state === 'disabled') {
110  // Explicitly disabled
111}
112</script>
113```
114 
115### Solution 3: Use null for "Not Set"
116 
117```vue
118<script setup lang="ts">
119interface Props {
120  // null = not set, false = explicitly off, true = explicitly on
121  selected: boolean | null
122}
123 
124const props = withDefaults(defineProps<Props>(), {
125  selected: null
126})
127 
128// Three distinct states
129if (props.selected === null) {
130  console.log('Selection not specified')
131} else if (props.selected) {
132  console.log('Selected')
133} else {
134  console.log('Explicitly not selected')
135}
136</script>
137```
138 
139## Boolean Casting Order
140 
141Vue also has special behavior when Boolean and String are both valid:
142 
143```typescript
144// Order matters in runtime declaration!
145defineProps({
146  // Boolean first: empty string becomes true
147  disabled: [Boolean, String]
148})
149 
150// <MyComponent disabled /> → disabled = true
151// <MyComponent disabled="" /> → disabled = true
152```
153 
154```typescript
155defineProps({
156  // String first: empty string stays as string
157  disabled: [String, Boolean]
158})
159 
160// <MyComponent disabled /> → disabled = ''
161// <MyComponent disabled="" /> → disabled = ''
162```
163 
164With type-based declaration, Boolean always takes priority for absent props.
165 
166## Common Bug Pattern
167 
168```vue
169<!-- Parent.vue -->
170<script setup lang="ts">
171const userPreferences = ref({
172  darkMode: undefined as boolean | undefined
173})
174 
175// Fetch preferences...
176onMounted(async () => {
177  userPreferences.value = await fetchPreferences()
178})
179</script>
180 
181<template>
182  <!-- Bug: undefined becomes false, not "inherit system preference" -->
183  <ThemeToggle :darkMode="userPreferences.darkMode" />
184</template>
185```
186 
187**Fix:**
188 
189```vue
190<script setup lang="ts">
191const userPreferences = ref<{
192  darkMode: boolean | null
193}>({
194  darkMode: null  // Use null for "not yet loaded"
195})
196</script>
197 
198<template>
199  <!-- Now ThemeToggle can distinguish between null and false -->
200  <ThemeToggle :darkMode="userPreferences.darkMode" />
201</template>
202```
203 
204## TypeScript Type Accuracy
205 
206The Vue type system handles this, but it can be confusing:
207 
208```typescript
209interface Props {
210  disabled?: boolean
211}
212 
213const props = defineProps<Props>()
214 
215// At compile time: boolean | undefined
216// At runtime: boolean (never undefined due to Vue's boolean casting)
217 
218// TypeScript is technically "wrong" here, but the withDefaults usage
219// or explicit false default can help align expectations
220```
221 
222## Reference
223- [Vue.js Props - Boolean Casting](https://vuejs.org/guide/components/props.html#boolean-casting)
224- [GitHub Issue: Boolean props default to false](https://github.com/vuejs/core/issues/8576)
225- [TypeScript Vue 3 Props](https://madewithlove.com/blog/typescript-vue-3-and-strongly-typed-props/)
226