NgxMatForm

NgxMatForm is an Angular library that allows you to dynamically create forms based on a schema.
It leverages Angular Reactive Forms and Angular Material components to generate forms with configurable fields, appearance, and validation.
You can render forms dynamically by passing a schema that defines the fields, their types, validation rules, and appearance.

---

🚀 Key Features

• Dynamic Form Generation: Automatically generate forms based on a schema, avoiding manual field definitions.
• Field Types: Supports multiple input types (text, email, number, date, autocomplete, etc.).
• Validation: Includes Angular Validators (required, minLength, maxLength, pattern, etc.) with customizable rules per field.
• Appearance Customization: Easily customize form field appearance using Angular Material styles (Outline, Filled, etc.).
• Responsive Layout: Flexible grid-based layout system for responsiveness across devices.
• Customizable Labels and Buttons: Configure button and field labels directly from the schema.

---

🧩 Compatibility Table

NgxMatForm Version	Angular Version	Angular Material Version	Node Version
3.1.0	20.x	20.x	22.x
3.0.0	20.x	20.x	22.x
2.0.0	20.x	19.x	22.x
1.7.0 → 1.0.0	19.x	19.x	20.x

---

📦 Installation

Install the library from npm:

npm install ngx-mat-form

With NgModule

In your app.module.ts:

import { NgxMatFormModule } from 'ngx-mat-form';

@NgModule({
  declarations: [AppComponent],
  imports: [
    NgxMatFormModule.forRoot({
      debug: true,
      locale: 'en-GB'
    })
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {}

🧱 NgxMatForm Component

Inputs

• ngxMatFormSchema (NgxMatFormSchema): Schema that defines the form structure.

Outputs

• onFormChanges (FormGroup): Emits when the form value changes.
• onSubmit (FormGroup): Emits when the form is submitted.
• onReset (void): Emits when the form is reset.

Example usage:

<ngx-mat-form
  [ngxMatFormSchema]="ngxMatFormSchema"
  (onFormChanges)="handleFormChanges($event)"
  (onSubmit)="handleSubmit($event)"
  (onReset)="handleReset($event)">
</ngx-mat-form>

---

⚙️ Module Configuration

The module accepts configuration options for debugging and locale settings.

Property	Type	Description	Example
debug	boolean	Enables internal logging	true
locale	string	Sets locale for dates and numbers	'en-GB'

---

📘 NgxMatForm Schema Properties

Defines the configuration for dynamic forms.

Property	Type	Description	Example
id	string	Unique form identifier	'DynamicFormSchemaId'
name	string	Name of the form	'DynamicFormSchemaName'
restore	boolean	Restores form state on initialization	true
storeKey	string	Key used for session storage	'ngx.mat.form.schema.myfeature'
labelButtons	object	Labels for action buttons	{ submit: 'Submit', clear: 'Clear' }
columns	number	Grid column count	4
fields	NgxMatField[]	Array of field configurations	—

---

🧩 NgxMatField Properties

Property	Type	Description	Example
id	string	Field identifier	'name-field'
name	string	Control name	'name'
label	string	Field label	'Name'
appearance	NgxMatFieldAppearance	Material appearance	NgxMatFieldAppearance.Outline
type	NgxFieldTypes	Input type	NgxFieldTypes.Text
placeholder	string	Input placeholder	'Enter your name'
availableValues	any[]	Values for select/radio fields	[{id: 1, label: 'Example'}]
isSelectMultiple	boolean	Allows multiple selections	true
displayProperty	string	Property name to display	'label'
valueProperty	string	Property name for value	'id'
minDate / maxDate	Date	Min/max date for pickers	new Date(2000,0,1)
retrieveOptionsUrl	string	API URL for autocomplete	'https://api.example.com'
retrieveOptions	object	Async autocomplete configuration	See below
validators	Array<object>	Validation rules	See below

Example retrieveOptions:

retrieveOptions: {
  parameter: 'name',
  async: true,
  characters: 3,
  responseProperty: 'results'
}

Example validators:

validators: [
  { validator: 'required', value: true },
  { validator: 'minLength', value: 2 }
]

🧰 NgxMatFormService

Utility service to interact with or modify a form schema.

Methods

• setFormProperty(property, value, schema)

  this.ngxMatFormService.setFormProperty('id', 'ngx-new-id', this.schema);

• setAvailableValues(field, values, schema)

  this.ngxMatFormService.setAvailableValues('gender', this.exampleOptions, this.schema);

• setProperty(field, property, value, schema)

  this.ngxMatFormService.setProperty('gender', 'valueProperty', 'versionId', this.schema);
  this.ngxMatFormService.setProperty('gender', 'displayProperty', 'code', this.schema);

• clearStorageValues(schema)

  this.ngxMatFormService.clearStorageValues(this.schema);

---

🧩 Example Schema

export const DynamicFormSchema: NgxMatDynamicForm = {
  id: 'DynamicFormSchemaId',
  name: 'DynamicFormSchemaName',
  restoreForm: true,
  storeKey: 'ngx.mat.form.schema.myfeature',
  labelButtons: {
    submit: 'Submit',
    clear: 'Clear',
    buttonPosition: NgxMatFormButtonPositions.Left
  },
  columns: 4,
  fields: [
    {
      id: 'name-field',
      name: 'name',
      label: 'Name',
      appearance: NgxMatFieldAppearance.Outline,
      type: NgxFieldTypes.Text,
      placeholder: 'Enter your name',
      validators: [{ validator: 'required', value: true }]
    },
    {
      id: 'gender-field',
      name: 'gender',
      label: 'Gender',
      type: NgxFieldTypes.Select,
      appearance: NgxMatFieldAppearance.Outline,
      placeholder: 'Select gender',
      displayProperty: 'label',
      valueProperty: 'id',
      isSelectMultiple: true,
      availableValues: [
        { id: 1, label: 'Male' },
        { id: 2, label: 'Female' },
        { id: 3, label: 'Other' }
      ]
    },
    {
      id: 'birthday-field',
      name: 'birthday',
      label: 'Birthday',
      type: NgxFieldTypes.Date,
      appearance: NgxMatFieldAppearance.Outline,
      placeholder: 'User birthday',
      hint: { left: 'Add the user birthday' },
      minDate: new Date(2000, 0, 1),
      maxDate: new Date(2030, 11, 31)
    },
    {
      id: 'friends-field',
      name: 'friends',
      label: 'Friends',
      type: NgxFieldTypes.Autocomplete,
      appearance: NgxMatFieldAppearance.Fill,
      placeholder: 'User friends',
      hint: { left: 'Add the user friends' },
      displayProperty: 'name',
      valueProperty: 'id',
      retrieveOptionsUrl: 'https://rickandmortyapi.com/api/character',
      retrieveOptions: {
        parameter: 'name',
        async: true,
        characters: 3,
        responseProperty: 'results'
      }
    }
  ]
};

---

🌟 Benefits

• Dynamic and Configurable: Add or remove fields, adjust types, or modify validation rules via schema.
• Reusable: Reuse the same schema across multiple components.
• Consistent Design: Built with Angular Material, ensuring a cohesive UI.
• Flexible Layout: Responsive and grid-based for adaptive layouts.
• Simple to Use: Define forms with minimal configuration.
• Reactive Forms Integration: Full compatibility with Angular Reactive Forms for validation.

---

🛠 Maintained by NgxMatForm Team