Master Uniapp Components in 15 Minutes: Built‑in and Custom Component Development for Code Reuse

Goal

Understand how to use Uniapp’s built‑in UI components, create custom components, and implement parent‑child communication to achieve code reuse and higher development efficiency.

Prerequisite

Assumes the development environment is set up and the reader is familiar with Uniapp project structure, basic syntax, and data binding.

What is a component?

A component is a reusable UI module such as a product card, navigation bar, or button group. By extracting repeated UI into a component, the same code can be used in multiple places, reducing duplication.

Built‑in components

Uniapp provides two categories of components: official built‑in components (view, text, image, swiper, etc.) that work out of the box, and custom components that developers can package for business reuse.

Four most frequently used built‑in components

view : basic container, equivalent to a div.

text : displays text, can only nest other text elements.

image : shows pictures, supports lazy loading and mode adaptation; the most common mode is widthFix (fixed width, auto height).

swiper : carousel component, essential for e‑commerce homepages; common attributes include indicator-dots, autoplay, and circular.

Quick start example

The following page demonstrates the four components together. The scoped style attribute isolates CSS to the current page.

<template>
  <view class="container">
    <!-- Text component -->
    <text class="title">Basic Component Demo</text>

    <!-- Image component -->
    <image src="/static/logo.png" mode="widthFix" class="logo"></image>

    <!-- Swiper component -->
    <swiper class="banner" indicator-dots autoplay circular>
      <swiper-item><image src="/static/banner1.jpg" mode="widthFix"></image></swiper-item>
      <swiper-item><image src="/static/banner2.jpg" mode="widthFix"></image></swiper-item>
    </swiper>

    <!-- Button -->
    <button type="primary" @click="showMsg">Click Demo</button>
  </view>
</template>

<script>
export default {
  methods: {
    showMsg() {
      uni.showToast({ title: 'Component interaction succeeded' })
    }
  }
}
</script>

<style scoped>
.container { padding: 20rpx; }
.title { font-size: 36rpx; font-weight: bold; }
.logo { width: 150rpx; margin: 20rpx 0; }
.banner { height: 300rpx; }
</style>

Custom component creation

Creating a custom component involves three steps: (1) add a new .vue file under the components directory, (2) write its template, style, and script, and (3) import, register, and use it in a page.

Example: goods‑card component

<template>
  <view class="card">
    <image :src="goods.image" mode="widthFix" class="goods-img"></image>
    <view class="name">{{ goods.name }}</view>
    <view class="price">¥{{ goods.price }}</view>
    <button size="mini" type="primary" @click="addToCart">Add to Cart</button>
  </view>
</template>

<script>
export default {
  // Receive product data from parent
  props: {
    goods: { type: Object, required: true }
  },
  methods: {
    addToCart() {
      // Emit event to parent with product ID
      this.$emit('add-cart', this.goods.id)
    }
  }
}
</script>

<style scoped>
.card { padding: 20rpx; border: 1rpx solid #eee; margin: 20rpx; }
.goods-img { width: 100%; height: 200rpx; }
.name { font-size: 28rpx; margin: 10rpx 0; }
.price { color: red; font-size: 32rpx; }
</style>

Using the custom component in a page

<template>
  <view>
    <goods-card
      v-for="item in goodsList"
      :key="item.id"
      :goods="item"
      @add-cart="handleAddCart">
    </goods-card>
  </view>
</template>

<script>
import goodsCard from '@/components/goods-card.vue'

export default {
  components: { goodsCard },
  data() {
    return {
      goodsList: [
        { id: 1, name: 'uniapp Practical Course', price: 99, image: '/static/goods1.jpg' },
        { id: 2, name: 'Frontend Handbook', price: 59, image: '/static/goods2.jpg' }
      ]
    }
  },
  methods: {
    handleAddCart(id) {
      uni.showToast({ title: `Added product ${id}` })
    }
  }
}
</script>

Parent‑child communication

Props (parent → child)

Parent binds data with :goods="item".

Child receives it via props: { goods: Object }.

$emit (child → parent)

Child triggers this.$emit('add-cart', data).

Parent listens with @add-cart="handleAddCart".

Key rules

Props are read‑only; a child cannot modify parent data directly.

Any change must be communicated through $emit to keep a unidirectional data flow.

Common troubleshooting

Component not displayed – verify the import statement and that the component is registered.

Props data not received – ensure the parent’s bound attribute name matches the child’s prop name.

Attempting to modify props in a child – use $emit instead, because props are read‑only.

Style conflicts – add the scoped attribute to the component’s <style> block to isolate CSS.