stack/packages/mosaic/framework/skills/vue-best-practices/reference/prop-boolean-casting-order.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Boolean Prop Type Order Affects Casting Behavior	MEDIUM	Wrong type order causes boolean props to be parsed as empty strings instead of true	gotcha	vue3 props boolean type-casting validation

Boolean Prop Type Order Affects Casting Behavior

Impact: MEDIUM - When a prop accepts multiple types including both Boolean and String, the order in the type array determines how attribute-only syntax (e.g., <Component disabled />) is parsed. Incorrect ordering can result in "" (empty string) instead of true.

Vue applies special boolean casting rules, but String appearing before Boolean disables this casting.

Task Checklist

• Place Boolean before String in type arrays when you want boolean casting
• Test attribute-only syntax (<Component disabled />) to verify expected behavior
• Consider using only Boolean type if the prop is truly boolean
• Document the expected usage if both String and Boolean are intentional

Incorrect:

<script setup>
// WRONG: String before Boolean disables boolean casting
defineProps({
  disabled: [String, Boolean], // disabled="" is parsed as empty string ""
});
</script>

<!-- In parent template -->
<MyComponent disabled />
<!-- props.disabled === "" (empty string, not true!) -->

<script setup>
defineProps({
  // PROBLEMATIC: Order matters and may cause confusion
  loading: [String, Boolean], // <Component loading /> gives ""
  active: [Boolean, String], // <Component active /> gives true
});
</script>

Correct:

<script setup>
// CORRECT: Boolean before String enables boolean casting
defineProps({
  disabled: [Boolean, String], // <Component disabled /> parsed as true
});
</script>

<!-- All of these work as expected -->
<MyComponent disabled />
<!-- props.disabled === true -->
<MyComponent :disabled="true" />
<!-- props.disabled === true -->
<MyComponent :disabled="false" />
<!-- props.disabled === false -->
<MyComponent disabled="custom" />
<!-- props.disabled === "custom" -->

<script setup>
// BEST: Use only Boolean if you don't need String values
defineProps({
  disabled: Boolean, // Clear intent, no ambiguity
});
</script>

Boolean Casting Rules

Prop Declaration	Template Usage	Resulting Value
Boolean	<C disabled />	true
Boolean	<C /> (absent)	false
[Boolean, String]	<C disabled />	true
[String, Boolean]	<C disabled />	"" (empty string)
[Boolean, Number]	<C disabled />	true
[Number, Boolean]	<C disabled />	true

Note: The String type is special - it's the only type that overrides Boolean casting when placed first.

When to Use Multiple Types

<script setup>
// Use case: Prop can be a boolean toggle OR a string configuration
defineProps({
  // Animation can be true/false OR a timing string like "fast", "slow"
  animate: {
    type: [Boolean, String], // Boolean first for casting
    default: false,
  },
});
</script>

<!-- Usage examples -->
<Dialog animate />
<!-- true - use default animation -->
<Dialog :animate="false" />
<!-- false - no animation -->
<Dialog animate="slow" />
<!-- "slow" - custom timing -->

Reference

• Vue.js Props - Boolean Casting