ng-error-tooltips

An Angular library for Reactive Forms and Signal Forms that displays tooltips on form inputs with errors.

The latest library version is compatible with Angular 22.
Starting with version 20.1.0, ng-error-tooltips is fully zoneless-compatible.

Migration note (Signal Forms)

Starting with version 21.3.x, the ErrorTooltipSigDirective no longer reads the form field via [formField].

You must now explicitly pass the field using [errorTooltipField]:

<input
  [formField]="signalForm.name"
  ngErrorTooltipSig
  [errorTooltipField]="signalForm.name">

---

Demo

https://mkeller1992.github.io/ng-error-tooltips/

---

Install

npm i ng-error-tooltips

---

Setup

Standalone apps (ApplicationConfig / app.config.ts)

import { ApplicationConfig, provideZonelessChangeDetection, signal } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideErrorTooltipOptions, provideErrorTooltips, type SupportedLanguage } from 'ng-error-tooltips';
import { validate } from '@angular/forms/signals';

import { routes } from './app.routes';

// Optional: use a signal when the language can change at runtime.
export const demoLang = signal<SupportedLanguage>('de');

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideZonelessChangeDetection(),

    // lang is optional (defaults to 'de')
	// Pass either a static language string ('de', 'en' or 'fr') or a Signal<SupportedLanguage>.
    // validate is only required for Signal Forms / CustomSigValidators
    provideErrorTooltips({ lang: demoLang, validate }),

    // Optional global defaults for all tooltips.
    // Local [options] and explicit inputs like [placement] or [textColor] can still override these values.
    provideErrorTooltipOptions({
      textColor: '#7f1d1d',
      backgroundColor: '#fff7ed',
      borderColor: '#f97316',
    }),
  ],
};

Tooltip options are merged in this order:

library defaults < provideErrorTooltipOptions(...) < [options] < explicit inputs

Directives

import {
  ErrorTooltipDirective,
  ErrorTooltipSigDirective,
  ErrorTooltipSigFormDirective,
} from 'ng-error-tooltips';

---

Usage

Reactive Forms

Define a reactive form with validators in your TypeScript component.
For applications with language switching support, use the CustomValidatorsI18n variants.

import { Component, inject } from '@angular/core';
import { FormBuilder, FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { ErrorTooltipDirective, CustomValidators } from 'ng-error-tooltips';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss',
  imports: [FormsModule, ReactiveFormsModule, ErrorTooltipDirective],
})
export class AppComponent {
  private readonly formBuilder = inject(FormBuilder);

  formGroup: FormGroup = this.formBuilder.group({
    nameInput: new FormControl<string>('', {
      validators: [
        CustomValidators.required(),
        CustomValidators.minLength(3),
      ],
    }),
  });
}

<form [formGroup]="formGroup" (ngSubmit)="submit()">
  <input
    ngErrorTooltip
    formControlName="nameInput"
    placeholder="Enter your name*"
    type="text">

  <button type="submit">Submit</button>
</form>

Signal Forms

import { Component, inject, signal, viewChild } from '@angular/core';
import { form, FormField, submit } from '@angular/forms/signals';
import { CustomSigValidators, ErrorTooltipSigDirective, ErrorTooltipSigFormDirective } from 'ng-error-tooltips';

interface Employee {
  name: string;
}

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  imports: [FormField, ErrorTooltipSigDirective, ErrorTooltipSigFormDirective],
})
export class AppComponent {
  private readonly v = inject(CustomSigValidators);

  readonly ttForm = viewChild(ErrorTooltipSigFormDirective);

  readonly employee = signal<Employee>({
    name: '',
  });

  readonly signalForm = form(this.employee, path => [
    this.v.requiredI18n(path.name),
    this.v.minLengthI18n(path.name, 3),
  ]);

  async submit() {
    // marks all fields touched + runs validation
    await submit(this.signalForm, async () => undefined);

    if (!this.signalForm().valid()) {
      // show all tooltips inside the container
      this.ttForm()?.showErrorTooltips();
    }
	else {
		this.ttForm()?.hideErrorTooltips();
	}
  }
}

<div ngErrorTooltipSigForm>
  <input
    [formField]="signalForm.name"
    ngErrorTooltipSig
    [errorTooltipField]="signalForm.name"    
    placeholder="Enter your name*"
    type="text">
</div>

<button type="button" (click)="submit()">Submit</button>

---

Three ways to pass additional properties

1. Set global defaults for all tooltips via provideErrorTooltipOptions(...) in your ApplicationConfig, as shown above in Setup > Standalone apps:

provideErrorTooltipOptions({
  textColor: '#7f1d1d',
  backgroundColor: '#fff7ed',
  borderColor: '#f97316',
});

2. Pass one or more properties via an ErrorTooltipOptions object:

import { ErrorTooltipOptions } from 'ng-error-tooltips';

tooltipOptions: ErrorTooltipOptions = {
  placement: 'right',
  textColor: '#7f1d1d',
  backgroundColor: '#fff7ed',
  borderColor: '#f97316',
};

<input
  formControlName="ageInput"
  ngErrorTooltip
  [options]="tooltipOptions"
  placeholder="Enter your age*"
  type="number">

3. Pass explicit inputs directly on the control:

<input
  ngErrorTooltip
  [placement]="'right'"
  formControlName="nameInput"
  placeholder="Enter your name*"
  type="text">

Note: Tooltip options are merged as library defaults < provideErrorTooltipOptions(...) < [options] < explicit inputs.

---

Internationalisation (i18n)

Starting with version 21.1.0, ng-error-tooltips supports reactive multi-language error messages.

If you do nothing, the tooltip falls back to German (de) error messages.

To enable language switching, provide the current language as a Signal<'de' | 'fr' | 'en'> using provideErrorTooltips.

Whenever the language signal changes, all visible error tooltips update automatically.

---

Properties

name	type	default	description
id	string | number	0	A custom id that can be assigned to the tooltip
showFirstErrorOnly	boolean	false	Whether the tooltip should only display the first error if multiple errors exist
placement	Placement	'bottom-left'	The position of the tooltip
zIndex	number	1101	The z-index of the tooltip
tooltipClass	string	''	Additional CSS classes applied to the tooltip (::ng-deep)
shadow	boolean	true	Whether the tooltip has a shadow
offset	number	8	Offset of the tooltip relative to the element
width	string	''	Fixed width of the tooltip
maxWidth	string	'350px'	Maximum width of the tooltip
textColor	string	''	Custom text color of the tooltip
backgroundColor	string	''	Custom background color of the tooltip
borderColor	string	''	Custom border color of the tooltip and arrow
pointerEvents	"auto" | "none"	'auto'	Whether the tooltip reacts to pointer events
appendTooltipToBody	boolean	true	Whether the tooltip should be appended to the document body. Set to false for Angular Material dialogs or other overlay-based components where body-appended tooltips may appear behind the overlay

---

Angular Vitest unit tests

Mocking ErrorTooltipDirective (Reactive Forms)

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { AppComponent } from './app.component';
import { ErrorTooltipDirective, MockErrorTooltipDirective } from 'ng-error-tooltips';
import { FormBuilder } from '@angular/forms';

describe('AppComponent', () => {
  let component: AppComponent;
  let fixture: ComponentFixture<AppComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [AppComponent],
      providers: [FormBuilder]
    })
    .overrideComponent(AppComponent, {
      remove: { imports: [ErrorTooltipDirective] },
      add: { imports: [MockErrorTooltipDirective] }
    })
    .compileComponents();

    fixture = TestBed.createComponent(AppComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });
});

Mocking ErrorTooltipSigDirective and ErrorTooltipSigFormDirective (Signal Forms)

import { ErrorTooltipSigDirective, MockErrorTooltipSigDirective } from 'ng-error-tooltips';

await TestBed.configureTestingModule({
  imports: [AppComponent],
})
  .overrideComponent(AppComponent, {
    remove: { imports: [ErrorTooltipSigDirective, ErrorTooltipSigFormDirective] },
    add: { imports: [MockErrorTooltipSigDirective, MockErrorTooltipSigFormDirective] }
  })
  .compileComponents();