@nova-design-system/nova-angular

v3.24.0

Published

5 days ago

Nova is a design system created by Elia Group to empower creators to efficiently build solutions that people love to use.

0High
0Medium
0Low

Nova Components Angular (Angular 17 and below)

If you are using Angular 18, please use @nova-design-system/nova-angular-18. For Angular 19, use @nova-design-system/nova-angular-19.

Nova Components Angular allows you to integrate Nova's native UI elements into your Angular applications. It provides flexibility in usage with both standalone components and module-based setups. This guide will walk you through the necessary steps for setting up and using Nova Components in your Angular project.

Installation

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-angular

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

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

Setting up Tailwind

Nova Angular requires Tailwind CSS for styling. Tailwind provides a powerful utility-first workflow and an optimized bundle size. Nova includes a dedicated Tailwind theme and plugin that map 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. While compatible with v3, some features may not work as expected. See the official Angular + Tailwind guide for more details.

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) for colors, spacing, typography, radii, shadows, and more.
Integration:
- novaTailwindTheme wires Nova tokens into Tailwind’s theme scales.
- The Nova Tailwind plugin exposes utilities and variants that reference those tokens, so your Tailwind classes resolve to Nova’s token values at runtime.
Why import tokens CSS? Import exactly 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.

1. Install Tailwind CSS

npm install tailwindcss @tailwindcss/postcss postcss

2. Configure PostCSS Plugins

Create a .postcssrc.json file in the root of your project and add the @tailwindcss/postcss plugin to your PostCSS configuration.

{
  "plugins": {
    "@tailwindcss/postcss": {}
  }
}

3. Create `tailwind.config.ts`

In the root of your project, create a tailwind.config.ts file and include the Nova theme:

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

export default {
  theme: novaTailwindTheme,
} satisfies Config

4. Configure Tailwind and Nova Plugin in `styles.css`

In ./src/styles.css, add the Tailwind import, the config path, the dark mode class, and the Nova plugin:

@import 'tailwindcss';

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

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

5. Include the Nova Tokens (Spark or Ocean)

Add the Nova Tokens CSS file to the styles array in your angular.json configuration:

{
  ...
  "styles": [
    "src/styles.css",
    "@nova-design-system/nova-base/dist/css/spark.css" // or ocean.css
  ],
  ...
}

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

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

Option 1: Angular.json Configuration (Recommended)

Add the Nova Font Pro URL to the styles array in your angular.json configuration:

"styles": [
  "contact-us-for-URL/nova-fonts-pro.css"
]

Option 2: Import in Styles.css

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

Option 3: HTML Integration

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

The font CSS includes both font definitions and a body { font-family: ... } rule to apply fonts across your Angular application.

Standalone Component Setup

If you're using Angular's standalone components, follow these steps:

1. Provide Nova Components

Add the defineCustomElements function to your app.config.ts file to make Nova Web Components available across your application:

import { ApplicationConfig, APP_INITIALIZER } from '@angular/core';
import { provideRouter } from '@angular/router';
import { defineCustomElements } from '@nova-design-system/nova-webcomponents/loader';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    {
      provide: APP_INITIALIZER,
      useFactory: () => defineCustomElements,
      deps: [],
      multi: true,
    }
  ],
};

2. Import Nova Components Module in Your Standalone Components

For any standalone component where you want to use Nova Components, add the NovaComponentsModule to the imports array in the component decorator:

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { NovaComponentsModule } from '@nova-design-system/nova-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet, NovaComponentsModule],
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Your component logic here
}

If you are using an older version than 17 and the above does not work, you will need to use the CUSTOM_ELEMENTS_SCHEMA. This removes strict type checking but allows the web components to be used:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Your component logic here
}

Module-Based Setup

If you're using Angular modules, the setup is straightforward:

1. Import Nova Components Module

In the module where you want to use Nova components, add the NovaComponentsModule to the imports array. This automatically adds the required providers:

import { NgModule, APP_INITIALIZER } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { NovaComponentsModule } from '@nova-design-system/nova-angular';
import { defineCustomElements } from '@nova-design-system/nova-webcomponents/loader';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    AppRoutingModule,
    NovaComponentsModule, // Add NovaComponentsModule here
  ],
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: () => defineCustomElements, // Add the nova initializer here
      deps: [],
      multi: true,
    },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

By including NovaComponentsModule in your imports, Nova's web components become available throughout the module.

Usage Example

Once set up, you can use Nova components in your Angular templates just like any other Angular component. Here’s an example of using an nv-button:

<nv-button danger (click)="incrementCount()">Count is {{ count }}</nv-button>

In your component class, you can manage the button's behavior:

export class AppComponent {
  count = 0;

  incrementCount() {
    this.count++;
  }
}

Handling Angular Forms with Nova Components

Nova Components Angular also supports seamless integration with Angular's reactive forms and template-driven forms through the NovaComponentsValueAccessorModule. This module provides value accessor directives that allow Nova components to work effortlessly with Angular forms.

Standalone Component Setup

When working with standalone components, you can easily integrate Nova components with Angular forms by importing the NovaComponentsValueAccessorModule. Here’s how you can set it up:

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { FormsModule } from '@angular/forms';
import {
  NovaComponentsModule,
  NovaComponentsValueAccessorModule,
} from '@nova-design-system/nova-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    RouterOutlet,
    NovaComponentsModule,
    FormsModule,
    NovaComponentsValueAccessorModule, // Import the Value Accessor Module here
  ],
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent {}

This setup allows Nova components to be used seamlessly with Angular forms in your standalone components.

Module-Based Setup

If you're using Angular modules, you can also integrate the value accessors by importing the NovaComponentsValueAccessorModule in your module:

import { NgModule, APP_INITIALIZER } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { FormsModule } from '@angular/forms';
import {
  NovaComponentsModule,
  NovaComponentsValueAccessorModule,
} from '@nova-design-system/nova-angular';
import { defineCustomElements } from '@nova-design-system/nova-webcomponents/loader';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    FormsModule,
    NovaComponentsModule, // Add NovaComponentsModule here
    NovaComponentsValueAccessorModule, // Import the Value Accessor Module here
  ],
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: () => defineCustomElements, // Add the nova initializer here
      deps: [],
      multi: true,
    },
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

This setup ensures that Nova components are fully compatible with Angular forms throughout your module.

Usage Example with Angular Forms

With the value accessors set up, you can now use Nova components within Angular forms. Here's an example:

<form>
  <nv-fieldtext [(ngModel)]="inputValue" name="input"></nv-fieldtext>
  <button type="submit">Submit</button>
</form>

In your component:

export class AppComponent {
  inputValue = 'hello';
}

This setup allows you to use nv-fieldtext just like any other Angular form control, complete with two-way binding and validation.

Conclusion

Nova Components Angular provides an easy and flexible way to incorporate Nova's UI components into your Angular projects, whether you prefer using standalone components or a module-based approach. With Tailwind as the styling layer and Nova’s token-driven plugin, you can build consistent, scalable UIs across your application.

For more detailed documentation and examples, refer to the official Nova documentation.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Nova Components Angular (Angular 17 and below)

Installation

Setting up Tailwind

About Tailwind and the Nova Plugin

1. Install Tailwind CSS

2. Configure PostCSS Plugins

3. Create tailwind.config.ts

4. Configure Tailwind and Nova Plugin in styles.css

5. Include the Nova Tokens (Spark or Ocean)

Nova Font Pro Integration

Option 1: Angular.json Configuration (Recommended)

Option 2: Import in Styles.css

Option 3: HTML Integration

Standalone Component Setup

1. Provide Nova Components

2. Import Nova Components Module in Your Standalone Components

Module-Based Setup

1. Import Nova Components Module

Usage Example

Handling Angular Forms with Nova Components

Standalone Component Setup

Module-Based Setup

Usage Example with Angular Forms

Conclusion

3. Create `tailwind.config.ts`

4. Configure Tailwind and Nova Plugin in `styles.css`