Getting Started With Web Components

Vivid components are built as web components. This means they are framework-agnostic and can be used with any framework or no framework at all.

Installation

Add the NPM package to your repository:

npm install @vonage/vivid

yarn add @vonage/vivid

pnpm add @vonage/vivid

Adding the vvd-root Class

The Vivid tokens require a vvd-root class to be present. It is recommended to add it on the <html> element, but it can also be added on a wrapping element to scope it to a certain part of the application.

<html class="vvd-root">
	...
</html>

Importing the Styles & Fonts

How to load CSS may vary from project to project, so we cannot provide a one-size-fits-all solution. Choose an appropriate method for your project.

See the list of styles that come with Vivid for more information.

/* Import Tokens For Light or Dark Theme */
@import '@vonage/vivid/styles/tokens/theme-light.css';
/* (Vonage only) Load Spezia Variable fonts */
@import '@vonage/vivid/styles/fonts/spezia-variable.css';
/* (Optional) Import Theme Styles */
@import '@vonage/vivid/styles/core/theme.css';
/* (Optional) Import Typography Styles */
@import '@vonage/vivid/styles/core/typography.css';
/* (Optional) Import Vivid 2 Compatibility Styles */
@import '@vonage/vivid/styles/tokens/vivid-2-compat.css';

/* Import Tokens For Light or Dark Theme */
@forward '@vonage/vivid/styles/tokens/theme-light.css';
/* (Vonage only) Load Spezia Variable fonts */
@forward '@vonage/vivid/styles/fonts/spezia-variable.css';
/* (Optional) Import Theme Styles */
@forward '@vonage/vivid/styles/core/theme.css';
/* (Optional) Import Typography Styles */
@forward '@vonage/vivid/styles/core/typography.css';
/* (Optional) Import Vivid 2 Compatibility Styles */
@forward '@vonage/vivid/styles/tokens/vivid-2-compat.css';

Vonage uses the brand-specific Spezia font.

If you are not working on a Vonage project, you should use the Montserrat and Roboto Mono fonts.

Add the following to your <head> to load them from Google Fonts:

<head>
	<!-- ... -->
	<link rel="preconnect" href="https://fonts.googleapis.com" />
	<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
	<link
		href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;500;600&family=Roboto+Mono:wght@400;500&display=swap"
		rel="stylesheet"
	/>
	<!-- ... -->
</head>

Usage

You have two options to import the components:

Using side effect imports to register them with the default vwc prefix.
Using a register function to register them with a custom prefix.

Import components in your project via:

import '@vonage/vivid/button';

And include in HTML:

<vwc-button label="Click me"></vwc-button>

Import components in your project via:

import { registerButton } from '@vonage/vivid';

registerButton('dashboard');

And include in HTML:

<dashboard-button label="Click me"></dashboard-button>

Remember to not include the default side effect import (import '@vonage/vivid/button';) anywhere when using the register function as it will register the default prefix.

Alternative: Using a CDN

As an alternative to installing the package, you can use a content delivery network (CDN) to load the components directly in your HTML.

Global CDNs can help quickly integrate content within HTML pages, fetching content from a URL, skipping local builds entirely.

Such practice is often used when working on POCs or reproduction environments.

Tools like UNPKG, jsDeliver, Skypack etc. are bound to deliver any content registered in the npm registry.

The following snippet fully renders a Vivid Button component:

<!-- import Montserrat & Roboto-Mono fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
	href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;500;600&family=Roboto+Mono:wght@400;500&display=swap"
	rel="stylesheet"
/>

<!-- import light theme style tokens -->
<link
	rel="stylesheet"
	href="https://unpkg.com/@vonage/vivid@3.x/styles/tokens/theme-light.css"
/>

<!-- import Vivid button component -->
<script
	type="module"
	src="https://unpkg.com/@vonage/vivid@3.x/button/index.js"
></script>

<!-- Part of the app (or a whole app) that contains vivid components -->
<div class="vvd-root">
	<vwc-button
		label="Click me"
		appearance="filled"
		connotation="cta"
	></vwc-button>
</div>