Migrating From Vivid 2.x to Vivid 3.x
Vivid 3.x has been rewritten from scratch.
It comes with almost all components that are available in Vivid 2.x, and many new ones.
All of them are better in both code and semantics. All the components are aligned with the HTML spec and are more accessible.
If you are migrating to Vivid 3.x, you can install it alongside Vivid 2.x for an easy and gradual migration.
| Before (Vivid 2.x) | After (Vivid 3.x) | |
|---|---|---|
heading |
headline |
|
| icon | type |
name |
| icon | trailingIcon |
icon-leading (default), icon-trailing |
| size | dense, enlarged |
super-condensed, condensed, normal, expanded |
| size (icon) | small, medium, large |
scale from -6 to 5,undefined: default to font-size |
| sizes - in layout | xs, md, lg |
small, medium, large |
| looks ( ghost, filled, outlined) |
layout |
appearance |
| in some components | dismissible |
removable |
| Before (Vivid 2.x) | After (Vivid 3.x) | Comments |
|---|---|---|
chip, chip-settag, tag-group |
tag, tag-group |
|
circular-progress |
progress-ring |
|
dropdown |
menu |
use header + action-items slots |
icon-button |
button |
|
linear-progress |
progress |
|
snackbar |
alert |
|
theme-switch |
switch |
|
top-app-bar, top-app-bar fixed |
header |
In Vivid 3.x we created separate components for different uses for the former list-item.
This is for better accessibility and HTML standards.
| Usage | Before (Vivid 2.x) | After (Vivid 3.x) |
|---|---|---|
| navigation | vwc-listvwc-list-itemvwc-list-expansion-panel |
navnav-itemnav-disclosure |
| menu | vwc-listvwc-list-item |
menu-itemmenu-item with role="menuitemcheckbox" menu-item with role="menuitemradio" |
| List items | vwc-check-list-item |
menu-item with role="menuitemcheckbox" |
vwc-radio-list-item |
menu-item with role="menuitemradio" |
|
| option Use inside Select/Combobox |
vwc-list-item |
option |
The project needs to import Vivid 2.x components individually and not as a whole package.
Before:
"@vonage/vivid": "^2.x.x"
...
After:
"@vonage/vvd-context": "^2.x.x",
"@vonage/vvd-core": "^2.x.x",
//import all Vivid 2.x components you are using in the project
"@vonage/vwc-accordion": "^2.x.x",
"@vonage/vwc-action-group": "^2.x.x",
"@vonage/vwc-audio": "^2.x.x",
"@vonage/vwc-button": "^2.x.x",
...
Before:
import { VWCButton } from '@vonage/vivid';
After:
import { VWCButton } from '@vonage/vwc-button';
You can now install Vivid 3.x as usual by following the Getting Started guides.
Make sure you follow the instructions for:
- Using a custom prefix (e.g.
vwc-3) - Loading the Vivid 2.x compatibility styles (
@vonage/vivid/styles/tokens/vivid-2-compat.css)
You need to add the Vivid 2.x class vvd-scheme-main to a descendant element of the vvd-root.
This is needed to ensure that Vivid 2.x tokens are not overridden by Vivid 3.x tokens.
<html class="vvd-root">
<body class="vvd-scheme-main">
...
</body>
</html>
You are now ready to start using Vivid 3.x components.
You will need to add the vvd-component class to every component to avoid a collision between Vivid 2.x and Vivid 3.x tokens.
If you are using Vivid Vue, this is done automatically for you.
<vwc-3-button
class="vvd-component"
label="Scoped Vivid 3.x Button"
></vwc-3-button>
After using Vivid 3.x exclusively, follow these steps:
- Remove Vivid 2.x from your package.json. You should only have
@vonage/vivid": "^3.x". - Remove the
vvd-componentclass from all the components. - Remove the
vvd-scheme-mainclass from the body. - Remove the import of
vivid2-compat.css.