---
title: Angular
slug: wip/angular
createdAt: 2023-10-09T06:59:55.087Z
---

# Angular

This guide will help you set up and integrate Cosmos web components into your Angular application using the `@cosmos/web-angular` package.

## Supported Versions

:::hint{type="info"}
We aim to align with the Angular team's [actively supported versions](https://angular.dev/reference/releases#actively-supported-versions). For `@cosmos/web-angular`:

- **Angular:** v18, v19, v20
- **TypeScript:** 5.8+

⚠️ Angular Support for versions 15 and below has been dropped with Cosmos version 8.3.0.

⚠️ Angular Support for version 16 has been dropped with Cosmos version 9.3.0.

⚠️ Angular Support for version 17 has been dropped with Cosmos version 9.12.0.
:::

## Prerequisites: Install Cosmos

Before integrating Cosmos components into your Angular application, you must complete the general Cosmos installation process. This includes:

- Configuring access to Red Bull's private npm registry via an `.npmrc` or `.yarnrc.yml` file.
- Installing the core `@cosmos/web-angular` package.
- Setting up the required custom fonts.

:::hint{type="warning"}
**➡️ Please follow the complete instructions on our dedicated [Installation Guide](https://cosmos.redbull.design/install).**

Once you have successfully installed `@cosmos/web-angular` and configured the fonts by following the installation guide, you can proceed with the steps below.
:::

## Angular Integration with `@cosmos/web-angular`

The `@cosmos/web-angular` package is the recommended way to use Cosmos web components in Angular applications. It provides Angular-specific wrappers that enhance integration and provide a better developer experience. (For historical context on package evolution, see the [deprecation roadmap](https://cosmos.redbull.design/components-deprecations-code#Hsi-z)).

::::hint{type="warning"}
⚠️ **Note on Deprecated Package**

With release v9.7.0, the Angular wrapper is provided as the standalone package `@cosmos/web-angular`. For projects upgrading from a previous version that might have used direct imports from the core ~~`@cosmos/web`~~ package for Angular integration, dependencies and imports should be updated to use `@cosmos/web-angular`.

:::CodeblockTabs
package.json

```json
"dependencies": {
  // "@cosmos/web": "9.6.0",
  "@cosmos/web-angular": "9.7.0"
}
```
:::
::::

The benefits of using these Stencil's component wrappers include:

- Angular component wrappers will be detached from change detection, preventing unnecessary repaints of your web component.
- Web component events will1 be converted to RxJS observables to align with Angular's `@Output()`and will not emit across component boundaries.
- The input web components can be used as control value accessors with Angular's reactive forms or `[ngModel]`.

### Usage with Standalone Components (Recommended for Angular 17+)

Angular 17+ defaults to a standalone component architecture. Import Cosmos components from `@cosmos/web-angular` and necessary Angular modules directly into your standalone components.

:::CodeblockTabs
app.component.ts

```typescript
import { Component } from '@angular/core';
import { CosmosButton, CosmosInput } from '@cosmos/web-angular'; // Import from @cosmos/web-angular

@Component({
  selector: 'app-root',
  standalone: true,
  templateUrl: './app.component.html',
  imports: [
    CosmosButton, // Importing individual Cosmos component
    CosmosInput   // Importing another Cosmos component
  ],
})
export class AppComponent {
  name = 'Max';
}
```
:::

:::CodeblockTabs
app.component.html

```html
<cosmos-button>Button</cosmos-button>
<cosmos-input [label]="'Your Name'" [(value)]="name"></cosmos-input>
```
:::

### NgModel / Reactive Forms with Standalone Components

Our input components from `@cosmos/web-angular` can be used with the `ngModel` directive or within reactive forms.

:::hint{type="warning"}
**☝️ Watch out**

- For `[(ngModel)]`, ensure `FormsModule` is imported into your standalone component.
- For reactive forms, ensure `ReactiveFormsModule` is imported into your standalone component.
:::

To use standalone Cosmos form fields (from `@cosmos/web-angular`) in dynamic forms or with `ngModel`, their corresponding **value-accessor directives must also be imported** from `@cosmos/web-angular`.

**Value-Accessor Directives (exported from&#x20;**`@cosmos/web-angular`**):**

| **Component**    | **Value-Accessor Directive**  |
| ---------------- | ----------------------------- |
| `CosmosInput`    | `CosmosInputValueAccessor`    |
| `CosmosTextarea` | `CosmosTextareaValueAccessor` |
| `CosmosCheckbox` | `CosmosCheckboxValueAccessor` |
| `CosmosRadio`    | `CosmosRadioValueAccessor`    |
| `CosmosSelect`   | `CosmosSelectValueAccessor`   |

**NgModel Example (Standalone)**

:::CodeblockTabs
app.component.ts

```typescript
import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { CosmosInput, CosmosInputValueAccessor } from '@cosmos/web-angular'; // Import from @cosmos/web-angular

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    FormsModule,
    CosmosInput,
    CosmosInputValueAccessor // Value accessor for CosmosInput
  ],
  templateUrl: './app.component.html',
})
export class AppComponent {
  name = 'Max';
}
```
:::

:::CodeblockTabs
app.component.html

```html
<h1>Hello {{ name }}!</h1>
<cosmos-input label="Your name" [(ngModel)]="name"></cosmos-input>
```
:::

**Reactive Forms Example (Standalone)**

:::CodeblockTabs
app.component.ts

```typescript
import { Component } from '@angular/core';
import { FormBuilder, Validators, ReactiveFormsModule } from '@angular/forms';
import { CommonModule } from '@angular/common';
import { 
  CosmosButton, 
  CosmosInput, 
  CosmosInputValueAccessor 
} from '@cosmos/web-angular'; // Import from @cosmos/web-angular

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    CommonModule,
    ReactiveFormsModule,
    CosmosInput,
    CosmosInputValueAccessor, // Value accessor for CosmosInput
    CosmosButton
  ],
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  myForm;

  constructor(private fb: FormBuilder) {
    this.myForm = this.fb.group({
      name: ['', Validators.required],
    });
  }

  onSubmit() {
    if (this.myForm.valid) {
      alert(JSON.stringify(this.myForm.value));
    }
  }
}
```
:::

:::CodeblockTabs
app.component.html

```html
<form [formGroup]="myForm" (ngSubmit)="onSubmit()">
  <p>Form Value: {{ myForm.value | json }}</p>
  <p>Form Status: {{ myForm.status }}</p>
  <cosmos-input
    label="Name"
    formControlName="name"
    [invalid]="myForm.get('name')?.invalid && myForm.get('name')?.touched"
  >
  </cosmos-input>
  <cosmos-button
    type="submit"
    [disabled]="!myForm.valid"
  >
    Submit
  </cosmos-button>
</form>
```
:::

### Usage with NgModules (Legacy / Non-Standalone Projects)

For projects still based on NgModules, @cosmos/web-angular offers ways to integrate Cosmos components. You can either import the entire CosmosModule or import individual components directly into your NgModule.

**Option 1: Importing `CosmosModule`**

:::CodeblockTabs
app.module.ts

```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { ReactiveFormsModule } from '@angular/forms'; // Example for Reactive Forms

import { AppComponent } from './app.component';
import { CosmosModule } from '@cosmos/web-angular'; // Import the main CosmosModule

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    ReactiveFormsModule, 
    CosmosModule // Add CosmosModule here
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {}
```
:::

**Option 2: Importing Individual Components (into an `NgModule`)**

:::CodeblockTabs
app.module.ts

```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { ReactiveFormsModule } from '@angular/forms';

import { AppComponent } from './app.component';
import {
  CosmosButton,
  CosmosInput,
  CosmosInputValueAccessor
} from '@cosmos/web-angular'; // Import from @cosmos/web-angular

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    ReactiveFormsModule,
    CosmosInput, // Import individual Cosmos component
    CosmosInputValueAccessor, // Value accessor for CosmosInput
    CosmosButton // Import individual Cosmos component
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {}
```
:::

The component (`app.component.ts`) and template (`app.component.html`) for NgModule-based apps would be similar to the standalone examples, but the component itself would not have the `standalone: true` flag or an `imports` array in its decorator.
