/vue-debug-guides

Use Type Casting in Templates for Union Types

Impact: MEDIUM - When using lang="ts" in Vue Single File Components, template expressions get strict type checking. If a variable has a union type, you may need inline type casting to access type-specific methods or properties.

Task Checklist

• Use (value as Type) syntax for type casting in templates
• Consider narrowing types in script before using in template
• Remember template type checking requires lang="ts" attribute
• For Vue CLI/webpack: ensure vue-loader >= 16.8.0

The Problem

When a variable has a union type, TypeScript cannot know which specific type it is at template compile time:

Template with type error:

<script setup lang="ts">
// Union type: could be string OR number
let x: string | number = 1
</script>

<template>
  <!-- ERROR: Property 'toFixed' does not exist on type 'string | number' -->
  {{ x.toFixed(2) }}
</template>

TypeScript correctly identifies that toFixed() only exists on number, not string.

Solution 1: Inline Type Casting

Use (value as Type) syntax directly in the template:

<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  <!-- CORRECT: Cast to number to access toFixed -->
  {{ (x as number).toFixed(2) }}
</template>

Solution 2: Computed Property (Preferred)

Create a computed property that narrows or transforms the type:

<script setup lang="ts">
import { ref, computed } from 'vue'

const value = ref<string | number>(1)

const formattedValue = computed(() => {
  if (typeof value.value === 'number') {
    return value.value.toFixed(2)
  }
  return value.value
})
</script>

<template>
  <!-- Clean template, type-safe logic in script -->
  {{ formattedValue }}
</template>

Solution 3: Type Guard Function

Define a type guard and use it in the template:

<script setup lang="ts">
import { ref } from 'vue'

const data = ref<string | number | null>(null)

function isNumber(val: unknown): val is number {
  return typeof val === 'number'
}

function formatNumber(val: number): string {
  return val.toFixed(2)
}
</script>

<template>
  <div v-if="isNumber(data)">
    {{ formatNumber(data) }}
  </div>
  <div v-else-if="data !== null">
    {{ data }}
  </div>
</template>

Common Use Cases

API Response Data

<script setup lang="ts">
interface ApiResponse {
  status: 'success' | 'error'
  data?: UserData
  error?: string
}

const response = ref<ApiResponse | null>(null)
</script>

<template>
  <div v-if="response?.status === 'success'">
    <!-- Cast to access data safely -->
    {{ (response as { data: UserData }).data.name }}
  </div>
</template>

Better approach with computed:

<script setup lang="ts">
const userData = computed(() => {
  if (response.value?.status === 'success') {
    return response.value.data
  }
  return null
})
</script>

<template>
  <div v-if="userData">
    {{ userData.name }}
  </div>
</template>

Event Handlers with Event Types

<script setup lang="ts">
function handleInput(event: Event) {
  // Cast to HTMLInputElement to access 'value'
  const value = (event.target as HTMLInputElement).value
  console.log(value)
}
</script>

<template>
  <input @input="handleInput" />
</template>

Array Item Access

<script setup lang="ts">
const items = ref<(string | number)[]>([1, 'two', 3])
</script>

<template>
  <ul>
    <li v-for="item in items" :key="item">
      <!-- Cast when you know the type -->
      <span v-if="typeof item === 'number'">
        Number: {{ (item as number).toFixed(1) }}
      </span>
      <span v-else>
        String: {{ (item as string).toUpperCase() }}
      </span>
    </li>
  </ul>
</template>

When Type Casting is Needed

Important Notes

Template Type Checking Requirements

Template type checking is enabled when:

1. <script lang="ts"> or <script setup lang="ts"> is used
2. Vue Language Server (Volar) is active in your IDE
3. For webpack: vue-loader >= 16.8.0 is required

Avoid Excessive Casting

If you find yourself casting frequently in templates, consider:

• Moving logic to computed properties
• Using type guards in the script section
• Refactoring data structures to be more specific

Reference

• Vue.js TypeScript Overview - TypeScript in Templates
• Vue.js TypeScript with Composition API