Nova Components Vue

Nova Components Vue provides an easy way to use Nova’s native Web Components within your Vue applications.

Key Features

• Lightweight Integration: Leverage Nova Web Components with minimal configuration in Vue.
• Customizable Styling: Use Tailwind’s utility classes with the Nova CSS-only Tailwind plugin for token-driven styling and layouts.
• Dark Mode Ready: Toggle dark mode by adding the dark class to your body element.
• Nova Font Pro Support: Easily integrate Nova’s custom font for a consistent design experience.

Requirements

• ES2022+ build target — The Nova Vue plugin uses top-level await to ensure Stencil custom elements are registered before Vue renders. Your bundler must target es2022 or higher. For Vite, set build.target: 'es2022' in your vite.config.ts.

Installation

To begin, install the necessary Nova packages using your package manager:

npm install @nova-design-system/nova-webcomponents @nova-design-system/nova-base @nova-design-system/nova-vue

or

yarn add @nova-design-system/nova-webcomponents @nova-design-system/nova-base @nova-design-system/nova-vue

In some case, you might experience SSL certificate issues when working on Developers' VM. As documented in the Developers' setup guide, you need to turn off the SSL certificate verification:

npm config set strict-ssl false

Note for Yarn Users Yarn does not automatically install peer dependencies. You must install the following peer dependency manually:

yarn add @stencil/vue-output-target

Setting up Tailwind

Nova Vue requires Tailwind CSS for styling. Tailwind provides a powerful utility-first workflow and an optimized bundle size. Nova includes a CSS-only Tailwind plugin that maps Nova’s design tokens to Tailwind’s theme and utilities, enabling consistent, token-driven styling across your app.

Tailwind Version This guide is written for Tailwind v4.

About Tailwind and the Nova Plugin

• What is Tailwind? A utility-first CSS framework with low-level, composable classes (flex, grid, spacing, color, typography) to rapidly build UIs.
• Nova Tokens: Nova ships design tokens as CSS variables (via the Spark and Ocean themes) covering colors, spacing, typography, radii, shadows, and more.
• Integration: @nova-design-system/nova-base/theme/plugin.css wires Nova tokens into Tailwind’s theme scales and exposes utilities and variants that reference those tokens at runtime.
• Why import tokens CSS? Import one token CSS file (spark.css or ocean.css) so the underlying CSS variables exist at runtime. The Tailwind utilities generated by the plugin read from these variables.
• Do not mix with legacy utilities: When using Tailwind, do not import @nova-design-system/nova-base/dist/css/nova-utils.css to avoid redundant CSS and larger bundles.

Below is an example setup using the Vue CLI with Vite. If you're using another framework, such as Nuxt, please refer to the Tailwind Installation Guide.

1. Install Tailwind CSS and the Vite Plugin

npm install tailwindcss @tailwindcss/vite

Use the Tailwind CSS IntelliSense Extension to get full autocomplete support for Tailwind and Nova tokens.

2. Configure the Vite Plugin

Add the tailwindcss plugin to your vite.config.ts:

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
import vueDevTools from 'vite-plugin-vue-devtools'
import tailwindcss from '@tailwindcss/vite'

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue(), vueJsx(), vueDevTools(), tailwindcss()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

3. Configure Tailwind and Nova in main.css

In src/assets/main.css:

@import 'tailwindcss';
@import '@nova-design-system/nova-base/theme/plugin.css';
@import '@nova-design-system/nova-base/dist/css/spark.css';
/* Or import ocean.css instead of spark.css. */

Make sure to remove any other CSS that was generated by the Vue CLI.

No tailwind.config file, @config, @plugin, or separate JavaScript theme import is required. Do not combine theme/plugin.css with nova-utils.css.

Dark Mode To enable dark mode, add the dark class to the <body> element.

4. Register NovaComponents

Register the Nova Components Vue plugin in your main.ts file:

import './assets/main.css'

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { NovaComponents } from '@nova-design-system/nova-vue/plugin'

const app = createApp(App)

app.use(router)
app.use(NovaComponents)

app.mount('#app')

5. Use Nova Components with Tailwind Utilities

<script setup lang="ts">
import { ref } from 'vue'
import { NvButton } from '@nova-design-system/nova-vue'

const count = ref(0)
</script>

<template>
  <div class="flex items-center justify-center">
    <NvButton danger @click="count++">
      Count is {{ count }}
    </NvButton>
  </div>
</template>

Note: We have full TypeScript and IntelliSense support for Nova components. If you do not see autocomplete options, uninstall Volar/Vetur and use the Vue - Official extension only.

6. Setup the Nova Font

Follow the steps in the Nova Font Pro Integration section below.

Deprecated JavaScript configuration

The previous JavaScript theme and plugin remain available for backward compatibility. Do not combine this setup with theme/plugin.css.

tailwind.config.ts:

import type { Config } from 'tailwindcss'
import { novaTailwindTheme } from '@nova-design-system/nova-base/theme'

export default {
  theme: novaTailwindTheme,
} satisfies Config

src/assets/main.css:

@import 'tailwindcss';
@import '@nova-design-system/nova-base/dist/css/spark.css';

@config '../../tailwind.config.ts';
@plugin '@nova-design-system/nova-base/theme/plugin';
@custom-variant dark (&:where(.dark, .dark *));

Creating Your Own Style Components with Tailwind

If you find you’re repeating the same set of utility classes for certain UI elements (e.g., a card component), you can group them using Tailwind’s @apply keyword:

/* any css file */
.card {
  @apply bg-gray-50 dark:bg-gray-500 p-4 rounded-md shadow-sm;
}

Then in your markup, instead of:

<div class="bg-gray-50 dark:bg-gray-500 p-4 rounded-md shadow-sm">
  <!-- Content -->
</div>
<div class="bg-gray-50 dark:bg-gray-500 p-4 rounded-md shadow-sm">
  <!-- Content -->
</div>

You can use your new card class:

<div class="card">
  <!-- Content -->
</div>
<div class="card">
  <!-- Content -->
</div>

This ensures consistent styling and keeps your markup clean. Any colors or spacing used will reference the correct Nova Tokens.

Nova Font Pro Integration

[!WARNING] Nova Fonts is a protected asset and is not included in the Nova Base package. You need to include the Nova Fonts CSS file in your project. To get the Nova Fonts URL, please contact us via Teams or get the URL in the Nova Design System internal wiki.

Once you have the URL, you can integrate it using any of these methods:

Option 1: Import in Global CSS (Recommended)

In your src/assets/main.css:

@import url('contact-us-for-URL/nova-fonts-pro.css');

Option 2: HTML Integration

In your index.html:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="contact-us-for-URL/nova-fonts-pro.css">
</head>
<body>
  <div id="app"></div>
</body>
</html>

The nova-fonts-pro.css file includes both font definitions and the font-family rule for the body, automatically applying the fonts across your Vue application.