ngx-material-form-utils v0.2.1

Ngx-Material-form-utils

ngx-material-form-utils is a library that provides components which are used to simplify the creation of forms with Angular Material.

• Installation
• Error handling
• Input
• Textarea
• Select
• Form Status Indicator
• Action Confirm Directives
  • Submit Confirm
  • Click Confirm

Installation

At first, you should install the Angular Material and setup it. Learn more about the setup.

Install ngx-material-form-utils library:

$ npm install ngx-material-form-utils

Error handling

The library provides a directive mfuErrorMessage which is used to display error messages provided in InjectionToken.

Setup

Import MfuErrorMessage and VALIDATION_ERROR_MESSAGES_TOKEN in your module. Then provide VALIDATION_ERROR_MESSAGES_TOKEN with your custom error messages.

import { MfuErrorMessage, ValidationErrorMessages, VALIDATION_ERROR_MESSAGES_TOKEN } from 'ngx-material-form-utils';

const validationErrorMessages: ValidationErrorMessages = {
  required: () => 'This field is very required.',
}

NgModule({
  declarations: [
    ...
    MfuErrorMessage,
  ],
  providers: [
    {
      provide: VALIDATION_ERROR_MESSAGES_TOKEN,
      useValue: validationErrorMessages,
    },
  ],
})

If your validator returns some parameters, you can also use them in your error message. Example

const validationErrorMessages: ValidationErrorMessages = {
  minlength: (params) => `This field should be at least ${params.requiredLength} characters long.`,
  min: (error) => `The minimum value is ${error.min}. You entered ${error.actual}.`,
}

Usage

Add mfuErrorMessage to <mat-error> in your mat-form-field to allow displaying your error messages.

<mat-form-field appearance="outline">
<mat-label>Email</mat-label>
  <input
    formControlName="email"
    placeholder="Enter email"
    matInput
  />
  <mat-hint>Enter some email</mat-hint>
  <mat-error mfuErrorMessage></mat-error>
</mat-form-field>

Input field

The library provides a component mfu-input which is used to simplify the creation of input fields with Angular Material. Its a wrapper for mat-form-field with built-in error handling.

Setup

Import MfuInputComponent in your module.

import { MfuInputComponent } from 'ngx-material-form-utils';

NgModule({
  declarations: [
    ...
    MfuInputComponent,
  ]
})

Basic usage

Add mfuInput to your form.

component.ts

export class AppComponent {
  readonly fb = inject(FormBuilder);
  exampleForm = this.fb.group({
    username: ['', Validators.required]
  });
}

component.html

<form [formGroup]="exampleForm">
  <mfu-input controlName="username"/>
</form>

Errors are handled by default, but you should add error messages in your module by providing VALIDATION_ERROR_MESSAGES_TOKEN (example in error handling section).

mfu-input inputs

mfu-input outputs

mfu-input also exposes matInput element wrapped by mfu-input. You can access it by using ViewChild decorator in your component:

...
@ViewChild(MfuInputComponent) mfuInput: MfuInputComponent;
...
mfuInput.matInput

Textarea Component

The mfu-textarea component is a wrapper for the Angular Material textarea with built-in error handling.

Setup

Import MfuTextareaComponent in your module:

import { MfuTextareaComponent } from 'ngx-material-form-utils';
@NgModule({
  declarations: [
    ...
    MfuTextareaComponent,
  ]
})

Usage

Add mfu-textarea to your form:

component.ts

export class AppComponent {
  readonly fb = inject(FormBuilder);
  exampleForm = this.fb.group({
    description: ['', Validators.required]
  });
}

component.html

<form [formGroup]="exampleForm">
  <mfu-textarea controlName="description"/>
</form>

Errors are handled by default, but you should add error messages in your module by providing VALIDATION_ERROR_MESSAGES_TOKEN (example in error handling section).

mfu-textarea inputs

mfu-textarea outputs

mfu-textarea also exposes the matInput element wrapped by the component. You can access it by using the ViewChild decorator in your component:

...
@ViewChild(MfuTextareaComponent) mfuTextarea: MfuTextareaComponent;
...
mfuTextarea.matInput

Select Component

The mfu-select component is a wrapper for the Angular Material select with built-in error handling.

Setup

Import MfuSelectComponent in your module:

import { MfuSelectComponent } from 'ngx-material-form-utils';
@NgModule({
  declarations: [
    ...
    MfuSelectComponent,
  ]
})

Usage

Add mfu-select to your form:

component.ts

export class AppComponent {
  readonly fb = inject(FormBuilder);
  exampleForm = this.fb.group({
    country: ['', Validators.required]
  });

  countries = [
    { value: 'us', display: 'United States' },
    { value: 'ca', display: 'Canada' },
  ];
}

component.html

<form [formGroup]="exampleForm">
  <mfu-select controlName="country" [items]="countries"/>
</form>

Errors are handled by default, but you should add error messages in your module by providing VALIDATION_ERROR_MESSAGES_TOKEN (example in error handling section).

mfu-select inputs

mfu-select outputs

mfu-select also exposes the matSelect element wrapped by the component. You can access it by using the ViewChild decorator in your component:

...
@ViewChild(MfuSelectComponent) mfuSelect: MfuSelectComponent;
...
mfuSelect.matSelect

Form Status Indicator Component

The mfu-form-status-indicator component provides a visual representation of the overall status of a form, indicating whether the form is valid or invalid. It also supports smooth animations when the form status changes.

Setup

Import MfuFormStatusIndicatorComponent in your module:

import { MfuFormStatusIndicatorComponent } from 'ngx-material-form-utils';

@NgModule({
  declarations: [
    ...
    MfuFormStatusIndicatorComponent,
  ]
})

Usage

Add mfu-form-status-indicator to your form:

component.ts

export class AppComponent {
  readonly fb = inject(FormBuilder);
  exampleForm = this.fb.group({
    name: ['', Validators.required],
    age: ['', Validators.required]
  });
}

component.html

<form [formGroup]="exampleForm">
  <mfu-form-status-indicator/>
  <mfu-input controlName="name"/>
  <mfu-input controlName="age">
</form>

Form status indicator will be blank in initial state, invalid (red color bar) when some form control is invalid and touched and valid (green color bar) when all form controls are valid.

mfu-form-status-indicator inputs

By default, the component will display a colored bar above the form. The default colors are:

• Valid: green
• Invalid: red

You can change these colors by modifying the corresponding validColor and invalidColor input properties in your component.

Animations The mfu-form-status-indicator component includes smooth slide-in and slide-out animations for the status indicator. To disable animations, set the showAnimation input property to false.

Action Confirm Directives

ngx-material-form-utils provides two confirm directives: MfuSubmitConfirmDirective and MfuClickConfirmDirective. These directives allow you to prompt users with a angular material confirmation dialog before performing actions like form submission or button click events.

Setup

Both directives are part of MfuActionConfirmModule which you can import in your module:

import { MfuActionConfirmModule } from 'ngx-material-form-utils';

@NgModule({
  declarations: [
    ...
  ],
  imports: [
    ...
    MfuActionConfirmModule
  ]
})

MfuSubmitConfirmDirective

The MfuSubmitConfirmDirective is used to prompt users with a confirmation dialog before submitting a form. Directive should be added to the form element.

Usage

Add mfuSubmitConfirm to your form:

component.html

<form 
  [formGroup]="exampleForm"
  (confirmedSubmit)="onSubmit()" 
  mfuSubmitConfirm
>
  ...
</form>

Instead od listening to (ngSubmit), you should listen to (confirmedSubmit) event to respond to form submission only when the user confirms the action.

MfuSubmitConfirmDirective inputs

MfuSubmitConfirmDirective outputs

MfuClickConfirmDirective

The MfuClickConfirmDirective is used to prompt users with a confirmation dialog before performing a click event. Directive should be added to the button element.

Usage

Add mfuClickConfirm to your button:

component.html

<button 
  (confirmedClick)="onButtonClick()" 
  mfuClickConfirm
  type="button"
>
  Example button
</button>

Instead od listening to (click), you should listen to (confirmedClick) event to respond to button click only when the user confirms the action.

MfuClickConfirmDirective inputs

MfuClickConfirmDirective outputs