NgVuiTextInput Component Tutorial

A comprehensive guide to building robust forms with the ng-vui Text Input component, featuring built-in validation, error handling, SVG icons, and accessibility support.

📦 Installation

Install Required Dependencies

npm install @angular/core @angular/common @angular/forms @ng-vui/icon

📋 Required Dependencies

  • • @angular/core (^20.0.0)
  • • @angular/common (^20.0.0)
  • • @angular/forms (^20.0.0)
  • • @ng-vui/icon (^1.0.0) - For error icons and visual indicators

Import in Your Component

import { Component } from '@angular/core';
import { NgVuiTextInputComponent } from 'path/to/ng-vui-text-input';
import { NgVuiIconComponent } from '@ng-vui/icon';
import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';

@Component({
  selector: 'app-my-component',
  standalone: true,
  imports: [NgVuiTextInputComponent, NgVuiIconComponent, ReactiveFormsModule],
  // ... rest of component
})

⚠️ Important: CSS Setup for Proper Styling

If the text input's styling is not appearing correctly when used as an npm module, you need to import the component's CSS styles.

Method 1: Import CSS in your styles.css

/* Add to your src/styles.css file */
@import 'node_modules/@vui/text-input/text-input.css';

Method 2: Copy Required CSS

  1. Open node_modules/@vui/text-input/text-input.css
  2. Copy the entire CSS content
  3. Paste into your project's src/styles.css file
Visual Features You'll Get:
  • ✨ Rounded input fields with smooth borders
  • 🎯 Violet focus rings for accessibility
  • 🚨 Red error states with background tint and borders
  • 🔴 Error icons with animated messages
  • ⭐ Required field indicators with red asterisks
  • 🎨 Smooth transitions for all state changes

🎨 SVG Icon Integration

Enhanced with NgVuiIcon Component

The text input component now uses the @ng-vui/icon library for better visual consistency and scalability. Error states display professional SVG icons instead of emoji characters.

⚠️ Important Dependency

This component requires @ng-vui/icon to be installed and imported. Make sure to include NgVuiIconComponent in your component's imports array.

✨ Icon Features

  • • Professional SVG icons for error states
  • • Scalable and theme-aware design
  • • Consistent iconography across the component library
  • • Automatic color coordination with error states
  • • Improved accessibility with proper ARIA attributes

<div class="error-message">
  <ng-vui-icon
    name="exclamation-circle"
    size="16px"
    color="error"
    className="mr-1 flex-shrink-0">
  </ng-vui-icon>
  <span>Please enter a valid email address</span>
</div>

🚀 Basic Usage

Simple Text Input

Current value: "" 
<ng-vui-text-input
  label="Full Name"
  placeholder="Enter your full name"
  [(ngModel)]="name">
</ng-vui-text-input>

With Form Validation

@Component({
  template: `
    <form [formGroup]="userForm" (ngSubmit)="onSubmit()">
      <ng-vui-text-input
        label="Email Address"
        type="email"
        formControlName="email"
        requiredError="Email is required for registration"
        [submitted]="isSubmitted">
      </ng-vui-text-input>
      
      <button type="submit">Submit</button>
    </form>
  `
})
export class MyComponent {
  userForm = this.fb.group({
    email: ['', [Validators.required, Validators.email]]
  });
  
  isSubmitted = false;
  
  onSubmit() {
    this.isSubmitted = true;
    if (this.userForm.valid) {
      console.log('Form submitted!');
    }
  }
}

🚨 Error Handling & Validation

Built-in Validation Demo

Built-in Error Messages

  • Required: "This field is required" (customizable)
  • Email: "Please enter a valid email address"
  • Min Length: "Minimum length is X characters"
  • Max Length: "Maximum length is X characters"
  • Pattern: "Please enter a valid format"

🔧 Advanced Examples

Registration Form with Multiple Validations

@Component({
  template: `
    <form [formGroup]="registrationForm" (ngSubmit)="onRegister()">
      <ng-vui-text-input
        label="Email Address"
        type="email"
        formControlName="email"
        requiredError="Email is required to create your account"
        [submitted]="isSubmitted">
      </ng-vui-text-input>

      <ng-vui-text-input
        label="Password"
        type="password"
        formControlName="password"
        requiredError="Password is required for account security"
        [submitted]="isSubmitted">
      </ng-vui-text-input>
      
      <button type="submit">Create Account</button>
    </form>
  `
})
export class RegistrationComponent {
  registrationForm = this.fb.group({
    email: ['', [Validators.required, Validators.email]],
    password: ['', [Validators.required, Validators.minLength(8)]],
    username: ['', [
      Validators.required,
      Validators.minLength(3),
      Validators.pattern(/^[a-zA-Z0-9_]+$/)
    ]]
  });
}

Real-time Search with Event Handling

Status: Ready
Characters typed: 0
@Component({
  template: `
    <ng-vui-text-input
      label="Search Users"
      placeholder="Type to search users..."
      (input)="onSearchInput($event)"
      (blur)="onSearchBlur($event)"
      (change)="onSearchChange($event)">
    </ng-vui-text-input>
  `
})
export class SearchComponent {
  onSearchInput(value: string) {
    console.log('Searching for:', value);
    // Perform real-time search
  }
  
  onSearchBlur(value: string) {
    console.log('Search blurred with value:', value);
  }
}

📖 API Reference

Component Properties

Inputs

Property Type Default Description
label string '' Label text displayed above the input
type string 'text' HTML input type (text, email, password, etc.)
id string | undefined undefined Custom element ID (auto-generated if not provided)
placeholder string '' Placeholder text for the input field
requiredError string 'This field is required' Custom error message for required validation
customError string | null null Custom error message to override all validation errors
submitted boolean false Whether the parent form has been submitted

Supported Input Types

Type Description Example Use Case
text Default text input Names, titles, general text
email Email validation Email addresses with built-in validation
password Masked text input Passwords, secure fields
number Numeric input Ages, quantities, prices
tel Telephone number Phone numbers
url URL validation Website addresses
search Search input Search boxes
date Date picker Date selection
time Time picker Time selection
datetime-local Date and time Combined date/time selection

Outputs

Event Type Description
input EventEmitter<string> Emitted on every keystroke/input event
blur EventEmitter<string> Emitted when input loses focus
change EventEmitter<string> Emitted when input value changes and loses focus

💡 Best Practices

✅ Do

  • • Use meaningful labels and placeholders
  • • Handle form submission state properly with [submitted] binding
  • • Use appropriate input types (email, password, tel, etc.)
  • • Provide custom error messages for better user experience
  • • Use proper form validation with Angular validators
  • • Implement proper accessibility with labels and ARIA attributes

❌ Don't

  • • Use generic labels like "Input" or "Enter value"
  • • Forget to handle the submitted state for error display
  • • Ignore validation setup in your forms
  • • Use regular HTML inputs instead of the component
  • • Skip CSS imports when using as npm module
  • • Forget to import necessary Angular Forms modules