Skip to content

Commit 02ae9e6

Browse files
committed
feat: update custom elements interop migration guide for v-is deprecation
1 parent 8ca3f89 commit 02ae9e6

File tree

1 file changed

+6
-19
lines changed

1 file changed

+6
-19
lines changed

src/guide/migration/custom-elements-interop.md

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ badges:
99

1010
- **BREAKING:** The checks to determine whether tags should be treated as custom elements are now performed during template compilation, and should be configured via compiler options instead of runtime config.
1111
- **BREAKING:** Special `is` prop usage is restricted to the reserved `<component>` tag only.
12-
- **NEW:** There is new `v-is` directive to support 2.x use cases where `is` was used on native elements to work around native HTML parsing restrictions.
12+
- **NEW:** To support 2.x use cases where `is` was used on native elements to work around native HTML parsing restrictions, prefix the value with `vue:` to resolve it as a Vue component.
1313

1414
## Autonomous Custom Elements
1515

@@ -83,7 +83,7 @@ In 3.0, we are limiting Vue's special treatment of the `is` prop to the `<compon
8383
- 2.x behavior: renders the `bar` component.
8484
- 3.x behavior: renders the `foo` component and passing the `is` prop.
8585

86-
- When used on plain elements, it will be passed to the `createElement` call as the `is` option, and also rendered as a native attribute. This supports the usage of customized built-in elements.
86+
- When used on plain elements, it will be passed to the `createElement` call as the `is` prop, and also rendered as a native attribute. This supports the usage of customized built-in elements.
8787

8888
```html
8989
<button is="plastic-button">Click Me!</button>
@@ -96,7 +96,7 @@ In 3.0, we are limiting Vue's special treatment of the `is` prop to the `<compon
9696
document.createElement('button', { is: 'plastic-button' })
9797
```
9898

99-
## `v-is` for In-DOM Template Parsing Workarounds
99+
## `vue:` Prefix for In-DOM Template Parsing Workarounds
100100

101101
> Note: this section only affects cases where Vue templates are directly written in the page's HTML.
102102
> When using in-DOM templates, the template is subject to native HTML parsing rules. Some HTML elements, such as `<ul>`, `<ol>`, `<table>` and `<select>` have restrictions on what elements can appear inside them, and some elements such as `<li>`, `<tr>`, and `<option>` can only appear inside certain other elements.
@@ -113,29 +113,16 @@ In Vue 2 we recommended working around with these restrictions by using the `is`
113113
114114
### 3.x Syntax
115115
116-
With the behavior change of `is`, we introduce a new directive `v-is` for working around these cases:
116+
With the behavior change of `is`, a `vue:` prefix is now required to resolve the element as a Vue component:
117117
118118
```html
119119
<table>
120-
<tr v-is="'blog-post-row'"></tr>
120+
<tr is="vue:blog-post-row"></tr>
121121
</table>
122122
```
123123
124-
:::warning
125-
`v-is` functions like a dynamic 2.x `:is` binding - so to render a component by its registered name, its value should be a JavaScript string literal:
126-
127-
```html
128-
<!-- Incorrect, nothing will be rendered -->
129-
<tr v-is="blog-post-row"></tr>
130-
131-
<!-- Correct -->
132-
<tr v-is="'blog-post-row'"></tr>
133-
```
134-
135-
:::
136-
137124
## Migration Strategy
138125
139126
- Replace `config.ignoredElements` with either `vue-loader`'s `compilerOptions` (with the build step) or `app.config.isCustomElement` (with on-the-fly template compilation)
140127

141-
- Change all non-`<component>` tags with `is` usage to `<component is="...">` (for SFC templates) or `v-is` (for in-DOM templates).
128+
- Change all non-`<component>` tags with `is` usage to `<component is="...">` (for SFC templates) or prefix it with `vue:` (for in-DOM templates).

0 commit comments

Comments
 (0)