Nova Web Components (Vanilla)

Use Nova’s native Web Components directly in plain HTML/TypeScript without a framework. This package exposes the same UI components used across all Nova wrappers, ready to drop into any site or app.

• Nova Web Components (Vanilla)
  • Key Points
  • Installation
  • Setting up Tailwind
    • About Tailwind and the Nova Plugin
    • 1. Install Tailwind CSS
    • 2. Configure Vite
    • 3. Create tailwind.config.ts
    • 4. Configure Tailwind and the Nova Plugin in your CSS
    • 5. Import Nova Tokens (Spark or Ocean) and register components
    • 6. Use components in HTML with Tailwind utilities
    • Dark mode
  • Nova Font Pro Integration

Key Points

• Tailwind CSS is required. Nova’s Tailwind theme and plugin bind Nova design tokens to Tailwind’s utilities for consistent, token-driven styling.
• Do not import nova-utils.css when using Tailwind. The Tailwind pipeline produces a smaller, optimized bundle and richer utilities.
• Import exactly one token CSS file (spark.css or ocean.css) so the underlying CSS variables exist at runtime.

Installation

Install the required packages:

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

or

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

In some cases, 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

Setting up Tailwind

Nova Web Components rely on Tailwind for all of the utility classes. The Nova Tailwind theme and plugin map Nova’s tokens into Tailwind’s system, and generate utilities that resolve to token-backed CSS variables at runtime.

Tailwind version This guide targets Tailwind v4. While compatible with v3, some features may not work as expected.

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 quickly build UIs.
• Nova Tokens: Nova ships design tokens as CSS variables (Spark/Ocean themes) for colors, spacing, typography, radii, shadows, etc.
• Integration:
  • novaTailwindTheme wires Nova tokens into Tailwind’s theme scales.
  • The Nova Tailwind plugin emits utilities and variants that read those token variables at runtime.
• Why import tokens CSS? Import one of spark.css or ocean.css so the CSS variables exist. Tailwind utilities produced by the Nova plugin reference these variables.

1. Install Tailwind CSS

This example uses Vite, but there are multiple ways to set up Tailwind with your project. See the Tailwind documentation for more information.

npm install -D tailwindcss @tailwindcss/vite

Tip: Install the Tailwind CSS IntelliSense VS Code extension for autocomplete on Tailwind and Nova tokens.

2. Configure Vite

vite.config.ts:

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

3. Create tailwind.config.ts

In your project root:

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

export default {
  theme: novaTailwindTheme,
} satisfies Config

4. Configure Tailwind and the Nova Plugin in your CSS

Create a global CSS file (e.g., src/index.css) and add:

@import 'tailwindcss';

/* Adjust the path to your tailwind.config.ts as needed */
@config "../tailwind.config.ts";
@plugin "@nova-design-system/nova-base/theme/plugin";
@custom-variant dark (&:where(.dark, .dark *));

5. Import Nova Tokens (Spark or Ocean) and register components

Create src/setup.ts (or main.ts):

// Import ONE tokens theme so CSS variables exist at runtime
import '@nova-design-system/nova-base/dist/css/spark.css' // or ocean.css
import './index.css'

// Register Nova Web Components
import { defineCustomElements } from '@nova-design-system/nova-webcomponents/loader'
defineCustomElements()

Do not import @nova-design-system/nova-base/dist/css/nova-utils.css when using Tailwind.

6. Use components in HTML with Tailwind utilities

index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />
    <title>Nova Web Components</title>
    <script type="module" src="/src/setup.ts"></script>
  </head>
  <body class="min-h-screen flex items-center justify-center bg-background text-foreground">
    <!-- Layout with Tailwind utilities; styling flows into nv-* hosts (no shadow) -->
    <div class="flex flex-col items-center gap-4 p-6 rounded-md shadow-sm">
      <h1 class="text-2xl font-semibold">Nova Button</h1>
      <nv-button id="counter" danger>Click me</nv-button>
    </div>

    <script type="module">
      const button = document.getElementById('counter');
      let count = 0;
      button.addEventListener('click', () => {
        count += 1;
        button.textContent = `Count is ${count}`;
      });
    </script>
  </body>
</html>

• Use Tailwind utilities to create layouts (e.g., flex, grid, gap-*, p-*, m-*).
• Apply utilities directly to nv-* elements and surrounding/ slotted content to customize spacing and appearance.
• Consolidate repeated class patterns with Tailwind’s @apply in your own CSS utilities when useful.

Dark mode

Enable dark mode by adding the dark class on the body (or a root container):

<body class="dark">
  <!-- content -->
</body>

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, integrate it using one of the following:

• Import in global CSS (recommended):

  /* e.g., in src/index.css */
  @import url('contact-us-for-URL/nova-fonts-pro.css');

• Link in HTML:

  <link rel="stylesheet" href="contact-us-for-URL/nova-fonts-pro.css" />

The nova-fonts-pro.css file includes font-face definitions and a body { font-family: ... } rule to apply fonts across your application.