📘 Vue Props and Emits: Type-Safe Components

🎯 Introduction

Welcome to this exciting tutorial on Vue Props and Emits with TypeScript! 🎉 In this guide, we’ll explore how to create type-safe Vue components that communicate effectively with each other.

You’ll discover how proper typing of props and emits can transform your Vue development experience. Whether you’re building interactive user interfaces 🌐, complex data forms 📋, or reusable component libraries 📚, understanding type-safe component communication is essential for writing robust, maintainable Vue applications.

By the end of this tutorial, you’ll feel confident creating type-safe Vue components that communicate flawlessly! Let’s dive in! 🏊‍♂️

📚 Understanding Vue Props and Emits

🤔 What are Props and Emits?

Vue Props and Emits are like a conversation between parent and child components! 🗣️ Think of props as “gifts” 🎁 that parents give to children, and emits as “messages” 📨 that children send back to their parents.

In TypeScript terms, props define the data flowing down ⬇️ from parent to child, while emits define the events flowing up ⬆️ from child to parent. This means you can:

• ✨ Pass typed data to child components
• 🚀 Receive typed events from child components
• 🛡️ Catch communication errors at compile-time

💡 Why Use TypeScript with Vue Props and Emits?

Here’s why developers love type-safe Vue component communication:

1. Type Safety 🔒: Catch prop and emit errors at compile-time
2. Better IDE Support 💻: Autocomplete for props and event names
3. Self-Documenting Code 📖: Types serve as component API docs
4. Refactoring Confidence 🔧: Change component interfaces without fear

Real-world example: Imagine building a product card component 🛍️. With TypeScript, you can ensure the parent always passes the required product data and handles all possible events correctly!

🔧 Basic Syntax and Usage

📝 Simple Props Example

Let’s start with a friendly example:

<script setup lang="ts">
// 👋 Hello, Vue with TypeScript!
interface Props {
  title: string;        // 📋 Card title
  price: number;        // 💰 Product price
  emoji?: string;       // 🎨 Optional emoji
  isOnSale?: boolean;   // 🏷️ Sale status
}

// 🎯 Define props with TypeScript
const props = defineProps<Props>();

// 🎨 Computed value using props
const displayTitle = computed(() => 
  `${props.emoji || '📦'} ${props.title}`
);
</script>

<template>
  <div class="product-card">
    <h2>{{ displayTitle }}</h2>
    <p class="price">${{ price }}</p>
    <span v-if="isOnSale" class="sale-badge">🔥 On Sale!</span>
  </div>
</template>

💡 Explanation: Notice how we define a Props interface and use it with defineProps<Props>()! The ? makes properties optional.

🎯 Simple Emits Example

Here’s how to emit events with types:

<script setup lang="ts">
// 🏗️ Define emit events with TypeScript
interface Emits {
  addToCart: [product: { id: string; name: string }]; // 🛒 Add to cart
  toggleFavorite: [id: string];                       // ❤️ Toggle favorite
  priceAlert: [price: number, threshold: number];     // 💰 Price alert
}

// 🎨 Define emits with types
const emit = defineEmits<Emits>();

// 🎮 Using emits in functions
const handleAddToCart = () => {
  emit('addToCart', { 
    id: props.id, 
    name: props.title 
  });
  console.log(`🛒 Added ${props.title} to cart!`);
};

const handleFavoriteToggle = () => {
  emit('toggleFavorite', props.id);
  console.log(`❤️ Toggled favorite for ${props.title}!`);
};
</script>

💡 Practical Examples

🛍️ Example 1: Product Card Component

Let’s build a real product card:

<!-- ProductCard.vue -->
<script setup lang="ts">
// 🛍️ Product interface
interface Product {
  id: string;
  name: string;
  price: number;
  image: string;
  category: 'electronics' | 'clothing' | 'books';
  inStock: boolean;
  rating?: number;
}

// 📋 Component props
interface Props {
  product: Product;
  showRating?: boolean;
  size?: 'small' | 'medium' | 'large';
}

// 📢 Component emits
interface Emits {
  addToCart: [product: Product];
  viewDetails: [productId: string];
  addToWishlist: [productId: string];
  rateProduct: [productId: string, rating: number];
}

const props = withDefaults(defineProps<Props>(), {
  showRating: true,
  size: 'medium'
});

const emit = defineEmits<Emits>();

// 🎨 Computed properties
const cardClasses = computed(() => [
  'product-card',
  `product-card--${props.size}`,
  { 'product-card--out-of-stock': !props.product.inStock }
]);

const priceDisplay = computed(() => 
  `$${props.product.price.toFixed(2)} 💰`
);

const categoryEmoji = computed(() => {
  const emojis = {
    electronics: '💻',
    clothing: '👕',
    books: '📚'
  };
  return emojis[props.product.category];
});

// 🛒 Event handlers
const handleAddToCart = () => {
  if (!props.product.inStock) {
    console.log('⚠️ Product out of stock!');
    return;
  }
  
  emit('addToCart', props.product);
  console.log(`🛒 Added ${props.product.name} to cart!`);
};

const handleViewDetails = () => {
  emit('viewDetails', props.product.id);
  console.log(`👀 Viewing details for ${props.product.name}`);
};

const handleWishlist = () => {
  emit('addToWishlist', props.product.id);
  console.log(`❤️ Added ${props.product.name} to wishlist!`);
};

const handleRating = (rating: number) => {
  emit('rateProduct', props.product.id, rating);
  console.log(`⭐ Rated ${props.product.name}: ${rating} stars`);
};
</script>

<template>
  <div :class="cardClasses">
    <!-- 🖼️ Product image -->
    <img 
      :src="product.image" 
      :alt="product.name"
      class="product-image"
    />
    
    <!-- 📝 Product info -->
    <div class="product-info">
      <h3 class="product-title">
        {{ categoryEmoji }} {{ product.name }}
      </h3>
      
      <p class="product-price">{{ priceDisplay }}</p>
      
      <!-- ⭐ Rating display -->
      <div v-if="showRating && product.rating" class="rating">
        <span v-for="star in 5" :key="star">
          {{ star <= product.rating ? '⭐' : '☆' }}
        </span>
        <span class="rating-text">{{ product.rating }}/5</span>
      </div>
      
      <!-- 📦 Stock status -->
      <div class="stock-status">
        <span v-if="product.inStock" class="in-stock">
          ✅ In Stock
        </span>
        <span v-else class="out-of-stock">
          ❌ Out of Stock
        </span>
      </div>
    </div>
    
    <!-- 🎮 Action buttons -->
    <div class="product-actions">
      <button 
        @click="handleAddToCart"
        :disabled="!product.inStock"
        class="btn btn-primary"
      >
        🛒 Add to Cart
      </button>
      
      <button 
        @click="handleViewDetails"
        class="btn btn-secondary"
      >
        👀 Details
      </button>
      
      <button 
        @click="handleWishlist"
        class="btn btn-outline"
      >
        ❤️ Wishlist
      </button>
    </div>
    
    <!-- ⭐ Interactive rating -->
    <div v-if="showRating" class="rating-input">
      <span>Rate this product:</span>
      <button 
        v-for="star in 5" 
        :key="star"
        @click="handleRating(star)"
        class="star-btn"
      >
        {{ star <= (product.rating || 0) ? '⭐' : '☆' }}
      </button>
    </div>
  </div>
</template>

🎮 Example 2: Modal Dialog Component

Let’s create a flexible modal:

<!-- ModalDialog.vue -->
<script setup lang="ts">
// 🎭 Modal configuration
interface ModalProps {
  isVisible: boolean;
  title: string;
  size?: 'small' | 'medium' | 'large' | 'fullscreen';
  closable?: boolean;
  persistent?: boolean; // 🚫 Can't close by clicking outside
  showFooter?: boolean;
}

// 📢 Modal events
interface ModalEmits {
  close: [];
  confirm: [];
  cancel: [];
  opened: [];
  closed: [];
}

const props = withDefaults(defineProps<ModalProps>(), {
  size: 'medium',
  closable: true,
  persistent: false,
  showFooter: true
});

const emit = defineEmits<ModalEmits>();

// 🎨 Modal classes
const modalClasses = computed(() => [
  'modal',
  `modal--${props.size}`,
  { 'modal--persistent': props.persistent }
]);

// 🔒 Handle close attempts
const handleClose = () => {
  if (!props.closable) {
    console.log('🚫 Modal is not closable');
    return;
  }
  
  emit('close');
  emit('closed');
  console.log('🚪 Modal closed');
};

// 🎯 Handle overlay click
const handleOverlayClick = () => {
  if (props.persistent) {
    console.log('🛡️ Persistent modal - can\'t close by clicking outside');
    return;
  }
  
  handleClose();
};

// ✅ Handle confirm
const handleConfirm = () => {
  emit('confirm');
  console.log('✅ Modal confirmed');
};

// ❌ Handle cancel
const handleCancel = () => {
  emit('cancel');
  console.log('❌ Modal cancelled');
};

// 👀 Watch for visibility changes
watch(() => props.isVisible, (newValue) => {
  if (newValue) {
    emit('opened');
    console.log('👁️ Modal opened');
  }
});
</script>

<template>
  <Teleport to="body">
    <div 
      v-if="isVisible" 
      class="modal-overlay"
      @click="handleOverlayClick"
    >
      <div 
        :class="modalClasses"
        @click.stop
      >
        <!-- 📋 Modal header -->
        <header class="modal-header">
          <h2 class="modal-title">{{ title }}</h2>
          
          <button 
            v-if="closable"
            @click="handleClose"
            class="modal-close"
            aria-label="Close"
          >
            ❌
          </button>
        </header>
        
        <!-- 📄 Modal content -->
        <main class="modal-content">
          <slot></slot>
        </main>
        
        <!-- 🎮 Modal footer -->
        <footer v-if="showFooter" class="modal-footer">
          <slot name="footer">
            <button 
              @click="handleCancel"
              class="btn btn-secondary"
            >
              ❌ Cancel
            </button>
            <button 
              @click="handleConfirm"
              class="btn btn-primary"
            >
              ✅ Confirm
            </button>
          </slot>
        </footer>
      </div>
    </div>
  </Teleport>
</template>

🚀 Advanced Concepts

🧙‍♂️ Advanced Props with Validators

When you’re ready to level up, try custom prop validation:

<script setup lang="ts">
// 🎯 Advanced prop interface with constraints
interface AdvancedProps {
  email: string;
  age: number;
  priority: 'low' | 'medium' | 'high' | 'critical';
  tags: string[];
  metadata?: Record<string, unknown>;
}

// 🪄 Props with runtime validation
const props = defineProps<AdvancedProps>();

// 🛡️ Custom validation function
const validateEmail = (email: string): boolean => {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
};

const validateAge = (age: number): boolean => {
  return age >= 0 && age <= 150;
};

// ⚡ Computed validations
const isValidEmail = computed(() => validateEmail(props.email));
const isValidAge = computed(() => validateAge(props.age));
const validationErrors = computed(() => {
  const errors: string[] = [];
  
  if (!isValidEmail.value) {
    errors.push('📧 Invalid email format');
  }
  
  if (!isValidAge.value) {
    errors.push('🎂 Age must be between 0 and 150');
  }
  
  return errors;
});
</script>

🏗️ Advanced Emits with Payload Types

For complex event handling:

<script setup lang="ts">
// 🚀 Complex event payload types
interface UserAction {
  type: 'create' | 'update' | 'delete';
  userId: string;
  timestamp: Date;
  metadata?: Record<string, any>;
}

interface FormData {
  name: string;
  email: string;
  preferences: {
    notifications: boolean;
    theme: 'light' | 'dark';
    language: string;
  };
}

// 🎭 Advanced emits interface
interface AdvancedEmits {
  userAction: [action: UserAction];
  formSubmit: [data: FormData, isValid: boolean];
  error: [error: Error, context: string];
  progress: [current: number, total: number, message?: string];
}

const emit = defineEmits<AdvancedEmits>();

// 🎮 Advanced event handlers
const handleUserAction = (type: UserAction['type'], userId: string) => {
  const action: UserAction = {
    type,
    userId,
    timestamp: new Date(),
    metadata: { source: 'user-interface' }
  };
  
  emit('userAction', action);
  console.log(`🎯 User action: ${type} for user ${userId}`);
};

const handleFormSubmit = (formData: FormData) => {
  const isValid = validateForm(formData);
  emit('formSubmit', formData, isValid);
  
  if (isValid) {
    console.log('✅ Form submitted successfully!');
  } else {
    console.log('❌ Form validation failed');
  }
};
</script>

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Mutating Props Directly

<script setup lang="ts">
interface Props {
  items: string[];
}

const props = defineProps<Props>();

// ❌ Wrong - mutating props directly!
const addItem = (item: string) => {
  props.items.push(item); // 💥 Vue will warn about this!
};

// ✅ Correct - emit event to parent!
interface Emits {
  addItem: [item: string];
}

const emit = defineEmits<Emits>();

const addItem = (item: string) => {
  emit('addItem', item); // ✅ Let parent handle the change
  console.log(`📝 Requested to add: ${item}`);
};
</script>

🤯 Pitfall 2: Missing Required Props

<script setup lang="ts">
// ❌ Dangerous - no default for required prop!
interface Props {
  title: string;
  count: number;
  isActive?: boolean;
}

// ✅ Safe - provide defaults where appropriate!
const props = withDefaults(defineProps<Props>(), {
  isActive: false
  // Note: title and count are required, no defaults needed
});

// 🛡️ Always validate in parent component
const isValidProps = computed(() => {
  return props.title.length > 0 && props.count >= 0;
});
</script>

🛠️ Best Practices

1. 🎯 Be Specific with Props: Define exact types rather than generic objects
2. 📢 Name Emits Clearly: Use descriptive event names like userSelected not just select
3. 🛡️ Validate Props: Add runtime validation for critical props
4. 🎨 Use Defaults Wisely: Provide sensible defaults for optional props
5. ✨ Document Your API: Use JSDoc comments for complex prop interfaces

<script setup lang="ts">
/**
 * 📋 User profile card component
 * Displays user information with interactive actions
 */
interface Props {
  /** 👤 User data object */
  user: {
    id: string;
    name: string;
    email: string;
    avatar?: string;
  };
  
  /** 🎨 Card display variant */
  variant?: 'compact' | 'detailed' | 'minimal';
  
  /** 🔒 Whether user can be edited */
  editable?: boolean;
}

/**
 * 📢 Component events
 */
interface Emits {
  /** 👤 User profile was clicked */
  userClick: [userId: string];
  
  /** ✏️ Edit button was clicked */
  editUser: [userId: string];
  
  /** 📧 Email link was clicked */
  emailUser: [email: string];
}
</script>

🧪 Hands-On Exercise

🎯 Challenge: Build a Comment System

Create a type-safe comment component system:

📋 Requirements:

• ✅ Comment component with author, content, timestamp
• 🏷️ Support for replies (nested comments)
• 👍 Like/dislike functionality with vote counts
• ✏️ Edit and delete actions (with permissions)
• 🎨 Different display modes (compact, detailed)
• 📱 Responsive design considerations

🚀 Bonus Points:

• Add emoji reactions beyond like/dislike
• Implement comment threading
• Add moderation features
• Create a comment composer component

💡 Solution

<!-- Comment.vue -->
<script setup lang="ts">
// 💬 Comment data structure
interface Comment {
  id: string;
  content: string;
  author: {
    id: string;
    name: string;
    avatar?: string;
  };
  timestamp: Date;
  likes: number;
  dislikes: number;
  replies?: Comment[];
  isEdited?: boolean;
  parentId?: string;
}

// 📋 Component props
interface Props {
  comment: Comment;
  currentUserId?: string;
  mode?: 'compact' | 'detailed';
  level?: number; // For nested replies
  maxLevel?: number;
  showReplies?: boolean;
  allowEdit?: boolean;
  allowDelete?: boolean;
}

// 📢 Component emits
interface Emits {
  like: [commentId: string];
  dislike: [commentId: string];
  reply: [parentId: string, content: string];
  edit: [commentId: string, newContent: string];
  delete: [commentId: string];
  report: [commentId: string, reason: string];
}

const props = withDefaults(defineProps<Props>(), {
  mode: 'detailed',
  level: 0,
  maxLevel: 3,
  showReplies: true,
  allowEdit: true,
  allowDelete: true
});

const emit = defineEmits<Emits>();

// 🎨 Computed properties
const isAuthor = computed(() => 
  props.currentUserId === props.comment.author.id
);

const canReply = computed(() => 
  props.level < props.maxLevel
);

const commentClasses = computed(() => [
  'comment',
  `comment--${props.mode}`,
  `comment--level-${props.level}`,
  { 'comment--author': isAuthor.value }
]);

const timeAgo = computed(() => {
  const now = new Date();
  const diff = now.getTime() - props.comment.timestamp.getTime();
  const minutes = Math.floor(diff / 60000);
  
  if (minutes < 1) return 'Just now 🕐';
  if (minutes < 60) return `${minutes}m ago ⏰`;
  const hours = Math.floor(minutes / 60);
  if (hours < 24) return `${hours}h ago 🕑`;
  const days = Math.floor(hours / 24);
  return `${days}d ago 📅`;
});

// 🎮 State for interactions
const isEditing = ref(false);
const editContent = ref('');
const showReplyForm = ref(false);
const replyContent = ref('');

// 👍 Handle like
const handleLike = () => {
  emit('like', props.comment.id);
  console.log(`👍 Liked comment ${props.comment.id}`);
};

// 👎 Handle dislike
const handleDislike = () => {
  emit('dislike', props.comment.id);
  console.log(`👎 Disliked comment ${props.comment.id}`);
};

// ✏️ Handle edit
const startEdit = () => {
  isEditing.value = true;
  editContent.value = props.comment.content;
};

const saveEdit = () => {
  if (editContent.value.trim()) {
    emit('edit', props.comment.id, editContent.value.trim());
    isEditing.value = false;
    console.log(`✏️ Edited comment ${props.comment.id}`);
  }
};

const cancelEdit = () => {
  isEditing.value = false;
  editContent.value = '';
};

// 💬 Handle reply
const startReply = () => {
  showReplyForm.value = true;
};

const submitReply = () => {
  if (replyContent.value.trim()) {
    emit('reply', props.comment.id, replyContent.value.trim());
    showReplyForm.value = false;
    replyContent.value = '';
    console.log(`💬 Replied to comment ${props.comment.id}`);
  }
};

const cancelReply = () => {
  showReplyForm.value = false;
  replyContent.value = '';
};

// 🗑️ Handle delete
const handleDelete = () => {
  if (confirm('🗑️ Are you sure you want to delete this comment?')) {
    emit('delete', props.comment.id);
    console.log(`🗑️ Deleted comment ${props.comment.id}`);
  }
};
</script>

<template>
  <article :class="commentClasses">
    <!-- 👤 Comment header -->
    <header class="comment-header">
      <div class="comment-author">
        <img 
          v-if="comment.author.avatar"
          :src="comment.author.avatar"
          :alt="`${comment.author.name}'s avatar`"
          class="author-avatar"
        />
        <span v-else class="author-avatar-placeholder">
          {{ comment.author.name.charAt(0).toUpperCase() }}
        </span>
        
        <div class="author-info">
          <span class="author-name">{{ comment.author.name }}</span>
          <span v-if="isAuthor" class="author-badge">👤 You</span>
          <span class="comment-time">{{ timeAgo }}</span>
          <span v-if="comment.isEdited" class="edited-badge">✏️ Edited</span>
        </div>
      </div>
    </header>
    
    <!-- 📝 Comment content -->
    <div class="comment-body">
      <div v-if="!isEditing" class="comment-content">
        {{ comment.content }}
      </div>
      
      <!-- ✏️ Edit form -->
      <div v-else class="comment-edit">
        <textarea 
          v-model="editContent"
          class="edit-textarea"
          placeholder="Edit your comment..."
          @keydown.ctrl.enter="saveEdit"
        ></textarea>
        
        <div class="edit-actions">
          <button @click="saveEdit" class="btn btn-primary">
            ✅ Save
          </button>
          <button @click="cancelEdit" class="btn btn-secondary">
            ❌ Cancel
          </button>
        </div>
      </div>
    </div>
    
    <!-- 🎮 Comment actions -->
    <footer class="comment-actions">
      <div class="vote-actions">
        <button 
          @click="handleLike"
          class="vote-btn vote-btn--like"
        >
          👍 {{ comment.likes }}
        </button>
        
        <button 
          @click="handleDislike"
          class="vote-btn vote-btn--dislike"
        >
          👎 {{ comment.dislikes }}
        </button>
      </div>
      
      <div class="comment-menu">
        <button 
          v-if="canReply"
          @click="startReply"
          class="action-btn"
        >
          💬 Reply
        </button>
        
        <button 
          v-if="isAuthor && allowEdit"
          @click="startEdit"
          class="action-btn"
        >
          ✏️ Edit
        </button>
        
        <button 
          v-if="isAuthor && allowDelete"
          @click="handleDelete"
          class="action-btn action-btn--danger"
        >
          🗑️ Delete
        </button>
      </div>
    </footer>
    
    <!-- 💬 Reply form -->
    <div v-if="showReplyForm" class="reply-form">
      <textarea 
        v-model="replyContent"
        placeholder="Write a reply..."
        class="reply-textarea"
        @keydown.ctrl.enter="submitReply"
      ></textarea>
      
      <div class="reply-actions">
        <button @click="submitReply" class="btn btn-primary">
          💬 Reply
        </button>
        <button @click="cancelReply" class="btn btn-secondary">
          ❌ Cancel
        </button>
      </div>
    </div>
    
    <!-- 🔄 Nested replies -->
    <div 
      v-if="showReplies && comment.replies?.length"
      class="comment-replies"
    >
      <Comment
        v-for="reply in comment.replies"
        :key="reply.id"
        :comment="reply"
        :current-user-id="currentUserId"
        :mode="mode"
        :level="level + 1"
        :max-level="maxLevel"
        :show-replies="showReplies"
        :allow-edit="allowEdit"
        :allow-delete="allowDelete"
        @like="$emit('like', $event)"
        @dislike="$emit('dislike', $event)"
        @reply="$emit('reply', $event)"
        @edit="$emit('edit', $event)"
        @delete="$emit('delete', $event)"
        @report="$emit('report', $event)"
      />
    </div>
  </article>
</template>

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

• ✅ Create type-safe Vue props with interfaces and validation 💪
• ✅ Emit typed events from child to parent components 🛡️
• ✅ Avoid common mistakes like prop mutation and missing types 🎯
• ✅ Build complex component APIs with advanced prop and emit patterns 🐛
• ✅ Create reusable, documented components that are easy to use! 🚀

Remember: TypeScript with Vue makes component communication crystal clear! It’s like having a detailed instruction manual for every component. 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered Vue Props and Emits with TypeScript!

Here’s what to do next:

1. 💻 Practice with the comment system exercise above
2. 🏗️ Build a Vue app with multiple communicating components
3. 📚 Move on to our next tutorial: Vue Composables with TypeScript
4. 🌟 Share your type-safe Vue components with the community!

Remember: Every Vue expert was once a beginner. Keep building, keep typing, and most importantly, have fun with Vue and TypeScript! 🚀

Happy coding! 🎉🚀✨