This guide is intended to be a quick initiation into implementing Vega into products. It will provide the basics for installation and examples for how to create a few simple components.
Note: If you run into any issues with installation, please feel free to contact us at #vega-dev-support on Slack and we will work with you to ensure you get Vega running.
Further Note: Regarding compatibility across frameworks - While we perform testing during the Vega Release Cycle, occasionally there are some issues that can arise based on framework dependency configurations. For version reference, please review this guide to framework compatibility.
First, create a working directory where you want your new Vega site to live.
To install Vega, either use a CDN or install it locally through NPM.
Vega is published to the npmjs directory. Because of this, it is also accessible through UNPKG, which is an open source fast Content Delivery Network (CDN) for free.
To use Vega through a CDN, use UNPKG as the endpoint.
For example:
<head>
<script type="module" src="https://unpkg.com/@heartlandone/vega@1.29.0/dist/vega/vega.esm.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@heartlandone/vega@1.29.0/style/vega.css">
</head>
Note: UNPKG is hosted by the Cloudflare CDN provider as a free, best-effort service, however as a result they cannot provide any uptime or support guarantees. If you rely on Vega to serve a User Interface (UI) that is crucial to your business, we highly recommend you use the local module installation approach instead.
npm install @heartlandone/vega to install the necessary Vega dependency to your packageAfter installing/downloading the @heartlandone/vega package, you can open your code editor (e.g. VSCode) by entering > code .
Create an HTML file (e.g. index.html) at the root directory of your file server (it should live at the same level as node_modules) and add the following code to <head> section:
<script type="module" src="[Vega Package Dir]/dist/vega/vega.esm.js"></script>
For example:
<head>
<script type="module" src="./node_modules/@heartlandone/vega/dist/vega/vega.esm.js"></script>
<link rel="stylesheet" href="./node_modules/@heartlandone/vega/style/vega.css">
</head>
Try out the following example. Copy and paste the below code inside the body tags of your HTML document.
<vega-button id="checkout_btn" variant="primary" type="icon-right" icon="cart" class="v-mr-size-24" ripple=true>
Checkout
</vega-button>
<script>
document.getElementById("checkout_btn").addEventListener("click", (e)=> {
console.log("Click Checkout Button");
})
</script>Note: Opening files directly from their folders may not properly render Vega components. To get Vega to preview properly, you may need open your file with Live Server in VSCode (or whichever IDE you are using).
Version Requirement:
@angular/common>= 12.0.0,@angular/core>= 12.0.0
To install the Vega Angular wrapper, run the following command prompt in your terminal:
npm install @heartlandone/vega-angularAdd the Vega CSS file into angular.json :
"build": {
"options": {
"styles": ["node_modules/@heartlandone/vega/style/vega.css"]
}
}Import VegaComponentModule into your app module using the following:
// app.module.ts
import { VegaComponentModule } from '@heartlandone/vega-angular';
@NgModule({
imports: [VegaComponentModule],
})
For more troubleshooting information, view the README file.
<!-- In a component html file -->
<vega-button icon="cart" type="icon-right" class="v-w-full" (vegaClick)="clickButton($event)">
Checkout
</vega-button>
<vega-input
[(ngModel)]="vegaMaxNumberInputValue"
label="Max number is 10"
id="max-number-input-id"
max="10"
required="true"
>
</vega-input>
View a demo of a project using vega-angular.
Version Requirement:
react>= 16.7.0,react-dom>= 16.7.0
To install Vega using REACT, run the following command prompt in your terminal:
npm install @heartlandone/vega-reactImport the following required CSS styles into your index.js file.
import { createRoot } from "react-dom/client";
/* Core CSS required for Vega components to work properly */
import '@heartlandone/vega/style/vega.css'
import App from "./App";
const rootElement = document.getElementById("root");
const root = createRoot(rootElement);
root.render(<App />);The following is an example of using components, in your src/app.js file.
import { VegaButton, VegaInput } from "@heartlandone/vega-react";
export default function App() {
return (
<div className="App">
<VegaInput></VegaInput>
<VegaButton>Vega Button</VegaButton>
</div>
);
}Add @heartlandone/vega-react to your project as a dependency.
npm install @heartlandone/vega-reactAs Next.js doesn’t transpile or bundle node_modules in server (SSR) builds, adjusting the Next webpack configuration to transpile the ES modules of the released design system is necessary.
For this reason, you will also need to include the following additional configurations during your installation process:
npm install --save next-transpile-modules
Then update your next.config.js file to include:
const withTM = require('next-transpile-modules')(['@heartlandone/vega-react']);
const nextConfig = {
// Your original configuration in next.config.js
};
module.exports = withTM(nextConfig);Then include '@heartlandone/vega/style/vega.css' as a global CSS.
/* Core CSS required for Vega components to work properly */
import '@heartlandone/vega/style/vega.css'
export default function App({ Component, pageProps }) {
return <Component {...pageProps} />
}Below is an example of using Vega components in pages/index.tsx.
import { VegaButton, VegaInput } from "@heartlandone/vega-react";
export default function Home() {
return (
<div>
<VegaInput></VegaInput>
<VegaButton>Vega Button</VegaButton>
</div>
)
}Next.js is capable of automatically transpiling and bundling dependencies from local packages, superseding the need for the next-transpile-modules package. Read more: transpilePackages
Update next.config.js as follows:
const nextConfig = {
transpilePackages: ['@heartlandone/vega-react']
}
module.exports = nextConfigNote: NextJs v13 recommend using the App Router. If you’re using App Router please follow the below steps:
Import required CSS to app/layout.tsx.
/* Core CSS required for Vega components to work properly */
import '@heartlandone/vega/style/vega.css'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}Add the following to app/page.tsx. Don’t forget to add 'use client' at the top of the file.
For more information, see Client Components.
'use client'
import { VegaButton, VegaInput } from "@heartlandone/vega-react";
export default function Home() {
return (
<div>
<VegaInput></VegaInput>
<VegaButton>Vega Button</VegaButton>
</div>
)
}Error: Hydration failed because the initial UI does not match what was rendered on the server
Vega uses APIs in the browser context (such as ResizeObserver), which means it does not support server-side rendering (SSR).
To fix this issue, use the feature flag VEGA_REACT.PREVENT_SSR to disable SSR on Vega components.
// pages/_app.tsx
import '@heartlandone/vega/style/vega.css'
import { FeatureFlag } from "@heartlandone/vega";
FeatureFlag.enable("VEGA_REACT.PREVENT_SSR");
export default function App({ Component, pageProps }) {
return <Component {...pageProps} />
}
Additionally, if you are using useRef to store a reference to a Vega component, replace it with useVegaRef.
import React, { useEffect } from "react";
import { VegaForm, VegaInput, useVegaRef } from "@heartlandone/vega-react";
export default function Example() {
const formRef = useVegaRef();
useEffect(() => {
/**
* This hook will be called twice
* First time `formRef.current` will be `undefined` during SSR
* Second time `formRef.current` will be set when the Vega component is ready
*/
formRef.current?.setValue({name: "new value"});
}, [formRef.current]);
return (
<div>
<VegaForm ref={formRef}>
<VegaInput required={true} label="Name" data-vega-form="name" />
</VegaForm>
</div>
);
}
TypeError: Class extends value undefined is not a constructor or null
This might be caused by a React Class Component being rendered in a Server Component. React Class Components only work in Client Components.
Please refer to Next.js documentation for possible solutions: https://nextjs.org/docs/messages/class-component-in-server-componen
View a demo of Vega using vega-react
Version Requirement:
vue>= 3.0.0
To install @heartlandone/vega-vue into a project created by Vue-CLI, you can do so by running:
npm install @heartlandone/vega-vueThen, in your main.js or main.ts file, import the VegaComponentLibrary library plugin and use it with the following:
import { createApp } from 'vue';
import App from './App.vue';
// Import the style file of vega
import '@heartlandone/vega/style/vega.css';
// Import the VegaComponentLibrary Plugin
import { VegaComponentLibrary } from '@heartlandone/vega-vue';
const app = createApp(App).use(VegaComponentLibrary);
VegaComponentLibrary.isReady().then(() => {
app.mount('#app');
});
<script>
import { VegaCard, VegaAccordion, VegaInput } from "@heartlandone/vega-vue";
export default {
name: 'SimpleComponent',
components: {
VegaCard,
VegaAccordion,
VegaInput,
},
data: function () {
return {
accordionTitle: 'this is title',
emailValue: ''
};
},
};
</script>
<template>
<VegaCard background-color="bg-backdrop-popover" padding="size-32">
<VegaAccordion :accordion-title="accordionTitle">
<!--eslint-disable-next-line vue/no-deprecated-slot-attribute-->
<div slot="content">Email address you entered is {{ emailValue }}</div>
</VegaAccordion>
</VegaCard>
<VegaInput label="Email Address" required="true" email="true" v-model="emailValue"> </VegaInput>
</template>To install vega-vue into a project when using create-vue (based on Vite), run the following:
npm install @heartlandone/vega-vue
Then, in your main.js or main.ts file, use the following to import the vega-vue plugin library:
import { createApp } from 'vue';
import App from './App.vue';
// Import the VEga style file
import '@heartlandone/vega/style/vega.css';
// Import the VegaComponentLibrary Plugin
import { VegaComponentLibrary } from '@heartlandone/vega-vue';
const app = createApp(App).use(VegaComponentLibrary);
VegaComponentLibrary.isReady().then(() => {
app.mount('#app');
});
<template>
<VegaCard background-color="bg-backdrop-popover" padding="size-32">
<VegaAccordion :accordion-title="accordionTitle">
<!--eslint-disable-next-line vue/no-deprecated-slot-attribute-->
<div slot="content">Email address you entered is {{emailValue}}</div>
</VegaAccordion>
</VegaCard>
<VegaInput
label="Email Address"
:required="true"
:email='true'
v-model="emailValue"
>
</VegaInput>
</template>
<script lang="ts">
import { VegaCard, VegaAccordion, VegaInput } from "@heartlandone/vega-vue";
export default {
name: "SimpleComponent",
components: {
VegaCard,
VegaAccordion,
VegaInput,
},
data: function () {
return {
accordionTitle: "this is title",
emailValue: ""
};
},
created: function () {}
};
</script>
Note: The default usage of custom event handler for vue is @camelCase, if @lowercase is wanted, please disable feature flag
VEGA_VUE.EMIT_CAMEL_CASE_EVENT_NAMEin App.vue of the vue project
“slot attributes are deprecated vue/no-deprecated-slot-attribute”
The slots used in Stencil are Web Component slots, which are different than slots used in Vue 2. Unfortunately, the APIs for both are very similar, and your linter is likely confusing the two. You will need to update your lint rules in .eslintrc.js to ignore this warning:
module.exports = {
rules: {
'vue/no-deprecated-slot-attribute': 'off',
},
};
If you are using VSCode and have the Vetur plugin installed, you are likely getting this warning because of Vetur, and not ESLint. By default, Vetur loads the default Vue 3 linting rules and ignores any custom ESLint rules. To resolve this issue, you will need to turn off Vetur’s template validation with vetur.validation.template: false. See the Vetur Linting Guide for more information.