Installation
Add NeuralUI to your Angular 19+ project in 4 steps. First, check the dependencies your application must provide.
Install the package
Install the main package. The next step explains the dependencies your application must already provide.
npm install @neural-ui/coreAutomated setup and generators
The Angular schematics are additive, idempotent and compatible with Angular 19 through 22. They preserve existing application configuration and generate mobile-first standalone foundations.
# Add providers and global styles without removing existing configuration
ng add @neural-ui/core --project=my-app
# Generate an additive theme preset
ng generate @neural-ui/core:theme neural-ui-theme --path=src/styles --density=comfortable --theme=high-contrast
# Generate responsive standalone page foundations
ng generate @neural-ui/core:layout app-shell --project=my-app
ng generate @neural-ui/core:dashboard sales --project=my-app
ng generate @neural-ui/core:crud-page customers --project=my-app| Command | Files or configuration generated | Public options | How to revert |
|---|---|---|---|
ng add @neural-ui/core | Adds provideNeuralUI() to the root providers and registers the global stylesheet without removing existing entries. | --project, --skip-styles | Remove provideNeuralUI() and the Neural UI stylesheet entry that the command added. |
ng generate @neural-ui/core:theme | Creates src/styles/neural-ui-theme.scss by default with the selected density and optional high-contrast preset. | --name, --path, --density, --theme, --force | Remove the generated SCSS file and any import or data-neu-* attributes you added. |
ng generate @neural-ui/core:layout NAME | Creates NAME.component.ts, .html and .scss under the selected pages directory with a responsive sidebar and toolbar shell. | --project, --path, --force | Remove the generated directory and any route that you added for it. Existing routes are never changed automatically. |
ng generate @neural-ui/core:dashboard NAME | Creates NAME.component.ts, .html and .scss with responsive metric and card foundations. | --project, --path, --force | Remove the generated directory and any route that you added for it. Existing routes are never changed automatically. |
ng generate @neural-ui/core:crud-page NAME | Creates NAME.component.ts, .html and .scss with Reactive Forms, input, table and action foundations. | --project, --path, --force | Remove the generated directory and any route that you added for it. Existing routes are never changed automatically. |
Dependencies provided by your app (peer dependencies)
These are packages NeuralUI uses but does not bundle inside @neural-ui/core. Your application must have compatible versions installed. If it already uses Angular 19, 20, 21, or 22, you do not need to install Angular again.
| Package | Required version | When required |
|---|---|---|
@angular/cdk | >=19.0.0 <23.0.0 | |
@ng-icons/core | >=31.4.0 <34.0.0 | |
@ng-icons/lucide | >=31.4.0 <34.0.0 |
# Replace 21.2 with the major.minor used by your Angular app
npm install @angular/cdk@~21.2 @ng-icons/core @ng-icons/lucideConfigure providers
Register icons and configure providers in app.config.ts.
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideIcons } from '@ng-icons/core';
import { lucideCheck, lucideSearch } from '@ng-icons/lucide';
import { provideNeuralUI } from '@neural-ui/core';
import { routes } from './app.routes';
export const appConfig: ApplicationConfig = {
providers: [
provideRouter(routes),
provideNeuralUI(),
provideIcons({ lucideCheck, lucideSearch }),
],
};Icon registration example
NeuralUI renders the icon names you pass, but your app still needs to register those Lucide icons in the root providers.
// Register only the icons you actually use
import { ApplicationConfig } from '@angular/core';
import { provideIcons } from '@ng-icons/core';
import { lucideDownload, lucideSearch } from '@ng-icons/lucide';
export const appConfig: ApplicationConfig = {
providers: [
provideIcons({ lucideDownload, lucideSearch }),
],
};Import styles
Import the design tokens (required) and each component stylesheet you use.
/* styles.scss — one line to get all components and tokens */
@use '@neural-ui/core/styles' as *;Use your first component
Import the component in your standalone module and use it in the template.
// my.component.ts
import { NeuButtonComponent } from '@neural-ui/core/button';
@Component({
standalone: true,
imports: [NeuButtonComponent],
template: `<button neu-button variant="primary">Click me</button>`,
})
export class MyComponent {}<!-- app.component.html -->
<button neu-button variant="primary">
Hello NeuralUI!
</button>Angular version compatibility
NeuralUI supports Angular 19 through 22 (>=19 and <23). The library and this showcase are regularly built and tested with Angular 21.2.x; for the other versions, we verify that npm can install a compatible dependency set.
| Angular | Status | Notes |
|---|---|---|
22.x | npm can install Angular 22 and @ng-icons 33.x together; Chart has no Angular-specific wrapper dependency. | |
21.x | Major used by the showcase and the main build/test suite. The current environment resolves Angular 21.2.18 in the showcase and 21.2.17 in the ui-core workspace. | |
20.x | npm can install the compatible dependency set. Align all @angular/* packages and @angular/cdk to the same 20.x minor version. | |
19.x | Minimum declared version. Requires @ng-icons 31.4+; Chart has no Angular-specific wrapper dependency. | |
< 19 | Not supported. Requires the full signals API and zoneless compatibility. |
Browser compatibility
NeuralUI relies only on standard web APIs and runs on all modern evergreen browsers.
| Browser compatibility | Status | Notes |
|---|---|---|
| Chrome / Chromium | — | |
| Firefox | — | |
| Edge | — | |
| Safari 15+ | — | |
| Internet Explorer | Not supported. Angular dropped IE support in v13. |
Historical note: Angular 21.2.x and FormsModule
Some older Angular 21.2.x patch releases could break template-driven forms imports and surface NG3004 in projects using FormsModule. This is not active in the current environment.
Error shown during build
NG3004: Unable to import directive ɵNgNoValidate.
The symbol is not exported from @angular/forms/types/forms.d.ts (module '@angular/forms').Root cause
Those patch releases missed the ɵNgNoValidate export from @angular/forms/types/forms.d.ts, which broke FormsModule-based templates.
Recommended fix
If a consumer still sees NG3004, upgrade Angular to 21.2.8 or newer within the same major. NeuralUI and the showcase keep form examples on ReactiveFormsModule + FormControl.
// Historical: Angular 21.2.0 - 21.2.7 could trigger NG3004
// in legacy template-driven forms. Upgrade to 21.2.8+ or use Reactive Forms.// After: use ReactiveFormsModule + FormControl
import { FormControl, ReactiveFormsModule } from '@angular/forms';
@Component({
standalone: true,
imports: [ReactiveFormsModule],
template: `<neu-checkbox [formControl]="isChecked" label="Accept"></neu-checkbox>`,
})
export class MyComponent {
readonly isChecked = new FormControl(false, { nonNullable: true });
}