# @ngserveio/material-forms

> Find more at libraries and examples at [NgServe.io](https://ngserve.io).

Latest version **10.0.0** (published 2025-12-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ngserveio/material-forms
pnpm add @ngserveio/material-forms
yarn add @ngserveio/material-forms
bun add @ngserveio/material-forms
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 10.0.0 |
| Published | 2025-12-13 |
| First published | 2021-11-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 54.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Paul Mead |
| Maintainers | ngserve |
| Keywords | angular, navigation, forms, material, components, tailwind |

## Links

- npm: https://www.npmjs.com/package/@ngserveio/material-forms
- Homepage: https://github.com/mutableideas/ngserve-nx-gcp-starter/tree/master/libs/shared/ui/material-forms
- npm.io page: https://npm.io/package/@ngserveio/material-forms

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^2.3.0

## Alternatives

- [@progress/kendo-ooxml](https://npm.io/package/@progress/kendo-ooxml.md) — 152.1K weekly downloads
- [@progress/kendo-react-ripple](https://npm.io/package/@progress/kendo-react-ripple.md) — 8.0K weekly downloads
- [@progress/kendo-react-orgchart](https://npm.io/package/@progress/kendo-react-orgchart.md) — 4.3K weekly downloads
- [@praxisui/dynamic-fields](https://npm.io/package/@praxisui/dynamic-fields.md) — 2.4K weekly downloads
- [@mesalvo/react-ui](https://npm.io/package/@mesalvo/react-ui.md) — 1.7K weekly downloads

## Recent versions

- 10.0.0 (latest) — 2025-12-13
- 9.0.0 — 2024-10-14
- 8.1.1 — 2024-05-24
- 8.1.0 — 2024-05-18
- 8.0.0 — 2024-04-21
- 7.6.2 — 2024-02-24
- 7.6.1 — 2023-12-07
- 7.6.0 — 2023-11-16
- 7.5.0 — 2023-11-14
- 7.4.0 — 2023-11-12
- 7.3.0 — 2023-11-11
- 7.2.0 — 2023-11-11
- 7.0.2 — 2023-08-02
- 7.0.1 — 2023-07-29
- 7.0.0 — 2023-07-26
- … 30 more at https://npm.io/package/@ngserveio/material-forms/versions

## README

# @ngserveio/material-forms

Find more at libraries and examples at [NgServe.io](https://ngserve.io).

Read More At:
[Angular Tutorial - Part 1: Reusable Validation Messages](https://ngserve.io/angular-tutorial-reusable-validation-messages-part-1/)
[Angular Material Tutorial - Part 2: Creating a Reusable Form Field Component](https://ngserve.io/angular-material-tutorial-create-a-reusable-form-field-component/)

[1]: https://www.youtube.com/watch?v=zzILpCTH-3I
[2]: https://img.youtube.com/vi/zzILpCTH-3I/mqdefault.jpg

### See the Video Tutorial on YouTube

[![Angular Reactive Forms Validation with @ngserveio/validation-messages][2]][1]

## Running unit tests

Run `nx test shared-ui-material-forms` to execute the unit tests.

## Purpose

This library offers an easier way to validate forms using the Angular Material components.

## Import the NgServeMaterialFormsModule

```ts
import { NgServeMaterialFormsModule } from '@ngserveio/material-forms';
@NgModule({
  imports: [NgServeMaterialFormsModule],
})
export class SampleModule {}
```

### Form Field Validation Component

Displays the validations messages set on a particular control. Please refer to [Validation Error Messages Service](https://www.npmjs.com/package/@ngserveio/validation-messages) for customizing and interpolation of validation messages. This component in conjunction with [Validation Display Messages](https://www.npmjs.com/package/@ngserveio/validation-messages) avoids the need for duplicative markup.

#### Selector

`<ng-serve-form-field-validation></ng-serve-form-field-validation>`

#### Inputs

| Name        | Type                                                            | Description                                                                                                                                                              |
| ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fieldName` | string                                                          | The name of the field being validated. Will be used as a default parameter to interpolate in all validation messages. e.g. Message template `{{fieldName}} is required.` |
| `control`   | [AbstractControl](https://angular.io/api/forms/AbstractControl) | The control that's being validated.                                                                                                                                      |

#### Example

```ts
// Sample Component
import { Validators } from '@angular/forms';
import { FormGroupSubmit } from '@ngserveio/form-services';

@Component({
  template: 'sample-component',
})
export class SampleComponent {
  public formSamples = new FormGroupSubmit({
    firstName: new FormControl('', [Validators.required]),
  });

  public get firstName(): AbstractControl {
    return this.formSamples.get('firstName');
  }
}
```

```html
<form [formGroup]="formSamples">
  <!-- Please note the firstName name here is a string as a key in the formSamples formGroup -->
  <input type="text" formControlName="firstName" />

  <!-- firstName is the AbstractControl reference in the component code -->
  <ng-serve-form-field-validation [control]="firstName" fieldName="First Name">
  </ng-serve-form-field-validation>
</form>
```

### Form Field

The form field allows you to write less markup for displaying the label and validation and display the projected form field. Please not that the field must be of a [MatFormField](https://material.angular.io/components/form-field/overview) type.

#### Inputs

| Name      | Type                                                            | Description                                                                                                     |
| --------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `label`   | string                                                          | The label of the control and will also act as the `fieldName` input for the `ng-form-field-validation` control. |
| `control` | [AbstractControl](https://angular.io/api/forms/AbstractControl) | The control that's being validated.                                                                             |

#### Example

```ts
// Sample Component
import { Validators } from '@angular/forms';
import { FormGroupSubmit } from '@ngserveio/material-forms';

@Component({
  template: 'sample-component',
})
export class SampleComponent {
  public formSamples = new FormGroupSubmit({
    firstName: new FormControl('', [Validators.required]),
  });

  public get firstName(): AbstractControl {
    return this.formSamples.get('firstName');
  }
}
```

```html
<!-- Sample Component Markup -->

<form [formGroup]="formSamples">
  <ng-serve-form-field [control]="firstName" label="First Name">
    <input matInput type="text" formControlName="firstName">
  <ng-serve-form-field>
</form>
```

### Form

The form works in conjunction with the `FormGroupSubmit`. On submit of the form, the formGroup submit will mark `FormGroupSubmit` as submitted so validations can display based on whether or not the user has tried to submit the form.

#### Selector

`<ng-serve-form></ng-serve-form>`

#### Inputs

| Name               | Type                                          | Default Value | Description                                           |
| ------------------ | --------------------------------------------- | ------------- | ----------------------------------------------------- |
| `saveText`         | string                                        | `Save`        | The save text of the button that submits the form.    |
| `cancelText`       | string                                        | `Cancel`      | The cancel text of the button that cancels.           |
| `formCssClass`     | `string` &#124; `{ [name: string]: boolean }` | empty string  | The css class for the form.                           |
| `showCancelButton` | boolean                                       | true          | Determines whether or not to show the cancel button.  |
| `cancelDisabled`   | boolean                                       | false         | Disable the cancel button.                            |
| `saveDisabled`     | boolean                                       | false         | Disable the save button.                              |
| `saveButtonColor`  | string                                        | primary       | The material color of the display button.             |
| `saveButtonCss`    | `string` &#124; `{ [name: string]: boolean }` | empty string  | Determines the css for the save button.               |
| `formGroup`        | FormGroupSubmit                               | undefined     | The form group that helps mark the form as submitted. |

#### Outputs

| Name     | Type                 | Description                                      |
| -------- | -------------------- | ------------------------------------------------ |
| `cancel` | `EventEmitter<void>` | Emits when the user clicks the cancel button.    |
| `save`   | `EventEmitter<void>` | Emits a save event when the form group is valid. |

#### Example

```ts
// Sample Component
import { Validators } from '@angular/forms';
import { FormGroupSubmit } from '@ngserveio/material-forms';

@Component({
  template: 'sample-component',
})
export class SampleComponent {
  public formSamples = new FormGroupSubmit({
    firstName: new FormControl('', [Validators.required]),
  });

  public save(): void {
    console.log(this.formSamples.value);
  }

  public cancel(): void {
    console.log("I've been canceled!  Seems to be the culture.");
  }

  public get firstName(): AbstractControl {
    return this.formSamples.get('firstName');
  }
}
```

```html
<ng-serve-form [formGroup]="formSamples" (save)="save()" (cancel)="cancel()">
  <ng-serve-form-field [control]="firstName" label="First Name">
    <input matInput type="text" formControlName="firstName">
  <ng-serve-form-field>
</ng-serve-form>
```

### Content Projection

| Content Name | Required | Description                                     |
| ------------ | -------- | ----------------------------------------------- |
| default      | yes      | This area MUST CONTAIN a material input control |
| `prefix`     | no       |                                                 |
| `suffix`     | no       |                                                 |

[ChangeLog.md](./CHANGELOG.md)

## File Upload Components

These are components that allow for the display of and help of uploading files.

---
_Source: https://npm.io/package/@ngserveio/material-forms · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._