AquaDS Angular

✨ Design together. Build together. Speak the same language. ✨

npm i @aqua-ds/angular

Fully compatible with Angular's component system, including support for ngModel.

Installation

To integrate Aqua DS into an Angular project, follow these steps.

To integrate Aqua DS with an Angular project, follow these steps:

1. Ensure you have an Angular project initialized and you're using a recent version of Node.js and npm.
2. Install the Angular-compatible package:

npm i @aqua-ds/angular

Using Aqua DS Components

This is a basic example of how to use the <aq-button> component from Aqua DS in an Angular component.

// set-button.component.ts

import { Component } from '@angular/core';
import { AqButton } from '@aqua-ds/angular';

@Component({
  selector: 'app-set-button',
  imports: [AqButton],
  templateUrl: './set-button.component.html',
})

export class SetButtonComponent {
  handleClick(event: Event) {
    console.log('AqButton click from Angular ', event);
  }
}

<!-- set-button.component.html -->
<div>
	<aq-button (click)="handleClick($event)" variant="primary" type="submit">
		<i class="aq-icon-settings"></i>Button
	</aq-button>
</div>

Always refer to the documentation of each individual component for a complete list of supported events, their purpose, and usage examples.

Here’s how you can use components from the official list:

Components

Two-Way Binding with ngModel in Angular

If you plan to use ngModel with Aqua DS form components, you need to import and register the AWCValueAccessor. This allows Angular to communicate properly with the Web Component's value.

// set-text-field.component.ts

import { Component } from '@angular/core';
import { AqTextField, AWCValueAccessor } from '@aqua-ds/angular';
import { FormsModule, ReactiveFormsModule } from '@angular/forms'; 

@Component({
  selector: 'app-set-text-field',
  imports: [FormsModule, AWCValueAccessor, AqTextField],
  templateUrl: './set-text-field.component.html'
})

export class SetTextFieldComponent {
 textfieldValue = 'text'
}

<!-- set-text-field.component.html -->
<div>
	<aq-text-field [(ngModel)]="textfieldValue" placeholder="This has v-model" label="This is a label"></aq-text-field>
</div>

Aqua-DS components supports Angular’s [(ngModel)] two-way binding through native Angular forms. To enable this, make sure to:

1. Import the FormsModule from Angular.
2. Use the AwcValueAccessor utility from @aqua-ds/angular to connect Aqua Web Components with Angular’s form control system.

Tip: Ensure awcValueAccessor is applied to your form component or directive setup to bridge the value accessor layer properly

Handling Component Events

Aqua DS components emit custom DOM events that are fully compatible with Angular's event handling system. This means that you can use the (event) syntax to listen for these events, just as you would with any standard Angular component.

<aq-button 
	(click)="handleClick($event)"
	variant="primary"
	type="submit">
  Click Me
</aq-button>

import { Component } from '@angular/core';
import { AqButton } from '@aqua-ds/angular';

@Component({
  selector: 'app-set-button',
  imports: [AqButton],
  templateUrl: './set-button.component.html',
})
export class SetButtonComponent {
  handleClick(event: any) {
    console.log('AqButton click from Angular ', event);
  }
}

<aq-checkbox 
	id-checkbox="checkbox-1"
	name="checkbox-1"
	label="This is a checkbox 1"
	icon="aq-icon-message"
  required info="This is an information tooltip"
  value-checkbox="option3"
  (input)="handleValueChanged($event)">
 </aq-checkbox>

import { Component } from '@angular/core';
import { AqCheckbox} from '@aqua-ds/angular';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';

@Component({
  selector: 'app-set-checkbox',
  imports: [AqCheckbox],
  templateUrl: './set-checkbox.component.html',
})
export class SetCheckboxComponent {
  handleValueChanged(event: any) {
    console.log('Handling checkbox custom aqChange from Angular', event);
  }
}

Passing Properties to Components

When using Aqua DS components in Angular, you can pass properties just like you would with any other Angular component. Aqua DS supports standard HTML attributes and custom component-specific inputs. In Angular templates, you typically use property binding with square brackets[props] to pass data to component inputs.

<aq-button-split
    (clickRight)="handleClickRight($event)"
    (clickItem)="handleClickItem($event)"
    (clickLeft)="handleClickLeft($event)"
    variant="primary"
    size="medium"
    [items]="items"                
>Button Split</aq-button-split>

import { Component } from '@angular/core';
import { AqButtonSplit } from '@aqua-ds/angular';
@Component({
  selector: 'app-set-button-split',
  imports: [AqButtonSplit],
  templateUrl: './set-button-split.component.html',
})
export class SetButtonSplitComponent {
  items = [
    {
      id: 'id1',
      name: 'Item 1',
    },
    {
      id: 'id2',
      name: 'Item 2',
    },
  ];
  handleClickRight(event: any) {
    console.log('handleClickRight', event);
  }

  handleClickItem(event: any) {
    console.log('handleClickItem', event);
  }

  handleClickLeft(event: any) {
    console.log('handleClickLeft', event);
  }
}

Important Notes

In Angular, you also need to declare the Aqua DS components in the IMPORTS section of the @Component decorator to make them available within your template.

In Angular, the component class name is written in PascalCase (example: MyComponent), while the selector in the HTML is written in kebab-case (example: ). This facilitates readability and maintains consistency in the templates.

✨ Design together. Build together. Speak the same language. ✨