Nova.Design.System.Blazor 3.27.0

Nova Design System Integration Guide for Blazor

The Nova Design System provides reusable web components that work seamlessly with Blazor, including pre-styled components and a token-driven Tailwind setup for customization.

This guide explains how to integrate and use Nova components in a Blazor project, where components use the Nv prefix for their tags, such as NvButton and NvFieldtext.

Table of Contents

• Nova Design System Integration Guide for Blazor
  • Table of Contents
  • Installation
  • Setting up Tailwind
    • 1. Introduction
    • 2. Installing Node.js
    • 3. Initialize npm
    • 4. Install Tailwind CSS
    • 5. Create a CSS Source File
    • 6. Create the Tailwind Config File
    • 7. Add Build Scripts to .csproj
    • 8. Reference the Tailwind CSS and Nova Tokens in Your Project
  • Include Nova JavaScript
  • Building and upgrading
  • Nova Font Pro Integration
    • Option 1: HTML Link (Recommended)
    • Option 2: Import in Global CSS
  • Adding Nova Components in Blazor
    • Button Example
    • Input Text Example
    • Customizing Attributes
    • Use Tailwind CSS in Blazor Components
    • Handling Events with EventCallback
    • Two-Way Data Binding
      • Text Input
      • Checkbox
      • Dropdown
    • Custom Styles
      • Scoped CSS
  • Troubleshooting & FAQ
  • Additional Resources

Installation

IMPORTANT
Keep NuGet and NPM versions in sync. This package relies on matching versions between the NuGet package and the NPM base package @nova-design-system/nova-base used by the Tailwind pipeline and static assets. The build will emit a warning whenever these versions do not match.

1. Add the NuGet Package Install the Nova Design System NuGet package in your Blazor project:

   dotnet add package Nova.Design.System.Blazor
   

   Or add it manually to your .csproj file:

   <PackageReference Include="Nova.Design.System.Blazor" Version="x.y.z" />
   

2. Restore NuGet Packages

   dotnet restore
   

3. Verify the Package Ensure the package is correctly installed by checking the Dependencies section in your project or the obj folder.

Setting up Tailwind

This guide is written for Tailwind v4. While compatible with v3, some features may not work as expected.

1. Introduction

Nova for Blazor requires Tailwind CSS for styling. Nova includes a Tailwind theme and plugin that map design tokens to Tailwind utilities. Using Tailwind utility classes in your Blazor components provides:

• Better hot reload compatibility
• Modern styling standards
• Consistent design system integration

Nova ships design tokens as CSS variables with two theme options:

• Spark theme: _content/Nova.Design.System.Blazor/nova/spark.css
• Ocean theme: _content/Nova.Design.System.Blazor/nova/ocean.css

The novaTailwindTheme wires Nova tokens into Tailwind's theme scales, and the Nova plugin exposes utilities that reference these variables at runtime.

IMPORTANT
Import exactly one token theme CSS file (spark or ocean). Do not import legacy utilities when using Tailwind (e.g., nova-utils.css).

2. Installing Node.js

Node.js is required for npm to work. For Developers Using Elia Virtual Machines

1. Open the Software Center on your VM.
2. Search for Node.js and install the proposed version.

<img src="./nodejs-software-center.jpeg" alt="Node.js Installation via Software Center" width="60%">

3. Initialize npm

Initialize npm in your project directory (where your .csproj file is located):

npm init -y

This creates a package.json file to manage npm dependencies.

4. Install Tailwind CSS

In your project directory:

npm install tailwindcss@4.1.3 @tailwindcss/cli@4.1.3 @nova-design-system/nova-base@<version>

Replace <version> with your Nova.Design.System.Blazor NuGet version (check your .csproj). Example:

npm install tailwindcss@4.1.3 @tailwindcss/cli@4.1.3 @nova-design-system/nova-base@3.0.0

Example package.json dependencies:

{
  "dependencies": {
    "@nova-design-system/nova-base": "^3.0.0",
    "@tailwindcss/cli": "^4.1.3",
    "tailwindcss": "^4.1.3"
  }
}

On some developer VMs, you may need:

npm config set strict-ssl false

5. Create a CSS Source File

Create Styles/tailwind.css:

@import 'tailwindcss';

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

6. Create the Tailwind Config File

Create tailwind.config.ts at the project root:

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

export default {
  theme: novaTailwindTheme,
} satisfies Config;

If TypeScript is an issue, use tailwind.config.js:

import { novaTailwindTheme } from "@nova-design-system/nova-base/theme";

/** @type {import('tailwindcss').Config} */
const config = {
  theme: novaTailwindTheme,
};

export default config;

If you use JS config, update Styles/tailwind.css to:

@import 'tailwindcss';

@config "../tailwind.config.js";
@plugin "@nova-design-system/nova-base/theme/plugin";
@custom-variant dark (&:where(.dark, .dark *));
/* Add your custom CSS here */

7. Add Build Scripts to .csproj

Add Tailwind build/watch targets:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
  
  <Target Name="BuildTailwindCSS" BeforeTargets="Build">
    <Exec Command="npx @tailwindcss/cli -i ./Styles/tailwind.css -o ./wwwroot/css/tailwind.css" />
  </Target>

  
  <Target Name="WatchTailwindCSS" BeforeTargets="Watch">
    <Exec Command="npx @tailwindcss/cli -i ./Styles/tailwind.css -o ./wwwroot/css/tailwind.css --watch" />
  </Target>
</Project>

Optionally limit to Debug:

<Target Name="BuildTailwindCSS" BeforeTargets="Build" Condition="'$(Configuration)' == 'Debug'">
  <Exec Command="npx @tailwindcss/cli -i ./Styles/tailwind.css -o ./wwwroot/css/tailwind.css" />
</Target>

<Target Name="WatchTailwindCSS" BeforeTargets="Watch" Condition="'$(Configuration)' == 'Debug'">
  <Exec Command="npx @tailwindcss/cli -i ./Styles/tailwind.css -o ./wwwroot/css/tailwind.css --watch" />
</Target>

8. Reference the Tailwind CSS and Nova Tokens in Your Project

In _Host.cshtml (Server) or wwwroot/index.html (WASM), reference your compiled Tailwind CSS, then exactly one Nova token theme:

<link rel="stylesheet" href="css/tailwind.css" />


<link rel="stylesheet" href="_content/Nova.Design.System.Blazor/nova/spark.css" />

Do not include nova.css when using Tailwind. Do not import legacy nova-utils.css.

Dark mode:

<body class="dark">
  
</body>

Include Nova JavaScript

Add the required Nova scripts to your _Host.cshtml (Server) or wwwroot/index.html (WASM):

Development:

<script type="module" src="_content/Nova.Design.System.Blazor/nova/native.esm.js"></script>
<script src="_content/Nova.Design.System.Blazor/js/helper.js"></script>

Production:

<script type="module" src="_content/Nova.Design.System.Blazor/nova/native.esm.js"></script>
<script src="_content/Nova.Design.System.Blazor/js/helper.min.js"></script>

Use development versions during development for easier debugging, and minified versions in production for better performance.

Building and upgrading

• Development: dotnet watch — Tailwind rebuilds on changes.
• Production: dotnet build or dotnet publish — Tailwind CSS included in output.

When upgrading Nova to a new version, it's crucial to keep both NuGet and Nova specific npm packages in sync to ensure proper functionality. After changing versions, run npm install locally to ensure the Tailwind pipeline picks up the correct resources.

Nova Font Pro Integration

IMPORTANT
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, contact us via Teams or see the Nova Design System internal wiki.

Option 1: HTML Link (Recommended)

Add to _Host.cshtml or wwwroot/index.html:

<link rel="stylesheet" href="contact-us-for-URL" />

Option 2: Import in Global CSS

In Styles/tailwind.css (or another global CSS):

@import url('contact-us-for-URL');

The font CSS includes font-face definitions and typically applies a body { font-family: ... } rule across your application.

Adding Nova Components in Blazor

Use Nova components directly in your .razor files with Nv tags.

Button Example

<NvButton Type="@NvButton.TypeEnum.button" @onclick="HandleClick">
   Click Me
</NvButton>

Input Text Example

<NvFieldtext Label="Name" Placeholder="Enter your name" @bind-Value="user.name" />

Customizing Attributes

<NvButton Type="@NvButton.TypeEnum.button" Emphasis="@NvButton.EmphasisEnum.low" Disabled Danger Fluid Size="@NvButton.SizeEnum.sm" @onclick="HandleClick">
   Click Me
</NvButton>

Use Tailwind CSS in Blazor Components

<div class="flex items-center justify-center p-4">
  <h1 class="text-3xl font-bold">Hello, Tailwind CSS!</h1>
</div>

Handling Events with EventCallback

<NvButton @onclick="HandleClick">
   Click Me
</NvButton>

@code {
    private void HandleClick()
    {
        Console.WriteLine("Button clicked!");
    }
}

Passing parameters:

<NvButton @onclick="() => HandleClick(42)">
   Click Me
</NvButton>

@code {
    private void HandleClick(int param)
    {
        Console.WriteLine($"Button clicked with param: {param}");
    }
}

Two-Way Data Binding

Nova supports two-way data binding using @bind-Value or @bind-Checked for boolean fields.

Text Input

<NvFieldtext Label="Name" Placeholder="Enter your name" @bind-Value="name" />

@code {
    private string name;
}

Checkbox

<NvFieldcheckbox Label="I agree to the terms" @bind-Checked="isAgreed" />

@code {
    private bool isAgreed;
}

Dropdown

<NvFieldselect Label="Select a fruit" @bind-Value="selectedFruit">
    <option value="Apple">Apple</option>
    <option value="Banana">Banana</option>
    <option value="Cherry">Cherry</option>
</NvFieldselect>

@code {
    private string selectedFruit;
}

Custom Styles

To customize Nova components:

1. Create a .css file in your project.
2. Add your custom styles:

NvButton {
  --button-background-color: #4CAF50;
}

3. Reference it in your HTML:

<link href="css/custom-styles.css" rel="stylesheet" />

Scoped CSS

Use .razor.css files for scoped styles.

Example: MyComponent.razor.css

NvCard {
  --card-border-color: #f00;
}

Troubleshooting & FAQ

Q: I get errors running Tailwind build scripts. A: Ensure Node.js and npm are installed. On VMs with SSL issues, try npm config set strict-ssl false.

Q: How do I know which version of @nova-design-system/nova-base to install? A: Use the same version as your Nova.Design.System.Blazor NuGet package. Check your .csproj for the version number.

Q: My Nova components are not styled or not working. A: Ensure you included one theme stylesheet (spark.css or ocean.css) and that Tailwind is compiled and loaded. Do not include nova.css in the Tailwind setup.

Q: Components not recognized in my .razor files. A: Add the following line to your _Imports.razor file:

@using NovaComponents

This makes all Nova components available throughout your project.

Q: My custom styles are not being applied. A: Make sure your custom CSS loads after Nova theme files and Tailwind. For scoped styles, use .razor.css files and reference the generated .styles.css.

Q: I'm getting build warnings about version mismatches. A: The build will warn you when NuGet and NPM versions don't match. Align the @nova-design-system/nova-base version in your package.json with the NuGet package version and re-run npm install.

Q: I see call stacks referencing non-existent node_modules paths. A: This is expected with pre-bundled assets. After running npm install locally with aligned versions, these references should correspond to real local paths.

Q: My changes are not appearing in the browser. A: Ensure you're referencing the correct compiled CSS file in index.html or _Host.cshtml.

Q: My Nova components are not displaying at all. A: Confirm Nova CSS and JS files are included in index.html or _Host.cshtml. Double-check that you have included the correct Nova CSS and JS files. Only include one theme stylesheet (spark.css or ocean.css).

Q: I'm seeing JavaScript errors in the browser console. A: Check browser console for JavaScript errors. Verify correct paths to Nova scripts and ensure Blazor is configured for JavaScript interop.

Q: My custom styles are conflicting with Nova styles. A: Use scoped CSS to prevent style conflicts. Confirm custom styles use valid CSS variables and make sure your custom CSS is loaded after the Nova stylesheets. For scoped styles, use .razor.css files and reference the generated .styles.css in your HTML.

Additional Resources

• Nova Design System Documentation
• Blazor Official Documentation
• Nova GitHub Repository

For further assistance, contact the Nova Design System team or refer to the official documentation.