Uni‑App Black Magic: Overriding Built‑in HTML and SVG Tags

1. Background

The front‑end team chose uni‑app for cross‑platform mobile development, which allows a single codebase to target Web, mini‑programs, Android, and iOS. Because the organization also maintains legacy Vue2 and Vue3 projects, the team needed a component library that works across multiple stacks without heavy refactoring.

During development the authors discovered that uni‑app modifies Vue's runtime and ships custom webpack plugins, enabling "black‑magic" techniques such as overriding built‑in tags, conditional compilation, and automatic scoped‑style namespace injection.

2. Preparation

Two projects are created for comparison:

vue create vue2-project

vue create -p dcloudio/uni-preset-vue uni-app-project

Node version: 14.19.3, vue‑cli 4.5.13, Vue 2.7.14.

3. Overriding an HTML tag – button example

Original button markup:

<button>click me</button>

Attempting to replace it with a custom component fails because Vue treats button as a reserved tag. The error stack points to vue.runtime.esm.js@4946 and mentions isBuiltInTag and config.isReservedTag .

Solution: override Vue.config.isReservedTag and add the tag to an ignore list.

const overrideTags = ['button']
// Save original logic
const oldIsReservedTag = Vue.config.isReservedTag
Vue.config.isReservedTag = function (tag) {
  if (overrideTags.indexOf(tag) !== -1) {
    return false
  }
  return oldIsReservedTag(tag)
}

Register the component and add it to Vue.config.ignoredElements :

Vue.config.ignoredElements = ['uni-button']

After these changes the uni-button renders correctly, though a warning about an unknown custom element may still appear.

4. Overriding an SVG tag – image example

A custom uni-image component is created:

<template>
  <uni-image>
    <img :src="src">
  </uni-image>
</template>

<script>
export default {
  name: 'image',
  props: { src: { type: String, default: '' } }
}
</script>

<style>
uni-image {
  width: 320px;
  height: 240px;
  display: inline-block;
  overflow: hidden;
  position: relative;
}
</style>

The component is parsed but not rendered because the SVG namespace is applied to image . By overriding Vue.config.getTagNamespace the tag can be forced out of the SVG namespace.

const conflictTags = ['switch', 'image', 'text', 'view']
const oldGetTagNamespace = Vue.config.getTagNamespace
Vue.config.getTagNamespace = function (tag) {
  if (~conflictTags.indexOf(tag)) {
    return false
  }
  return oldGetTagNamespace(tag) || false
}

Finally, the main entry combines all three overrides:

import Vue from 'vue'
import App from './App.vue'

Vue.config.productionTip = false

// 1) Ignore custom elements
Vue.config.ignoredElements = ['uni-button', 'uni-image']

// 2) Allow overriding of built‑in HTML tags
const overrideTags = ['button', 'image']
const oldIsReservedTag = Vue.config.isReservedTag
Vue.config.isReservedTag = function (tag) {
  if (overrideTags.indexOf(tag) !== -1) {
    return false
  }
  return oldIsReservedTag(tag)
}

// 3) Resolve namespace conflicts for SVG tags
const conflictTags = ['image']
const oldGetTagNamespace = Vue.config.getTagNamespace
Vue.config.getTagNamespace = function (tag) {
  if (~conflictTags.indexOf(tag)) {
    return false
  }
  return oldGetTagNamespace(tag)
}

new Vue({ render: h => h(App) }).$mount('#app')

5. Summary

Vue leaves a small backdoor that allows developers to rewrite the handling of built‑in tags, which makes it possible to create cross‑platform component libraries for uni‑app without forking the framework. These "black‑magic" techniques, while not documented officially, provide powerful ways to solve practical integration problems.