Angular Creating Custom Pipes Complete Guide

Angular Custom Pipes: Complete Example, Step by Step

1. Setting Up the Environment

Let's assume you already have an Angular project created. If not, you can create one using Angular CLI.

# Create a new Angular project
ng new my-angular-app

# Navigate into your newly created project directory
cd my-angular-app

# Serve your application to check if it’s running
ng serve

2. Generating a New Pipe

You can generate a new pipe using the Angular CLI or manually. Here, we will use Angular CLI to generate a pipe automatically. Let's create a pipe called capitalize.

# Generate a new pipe named 'capitalize'
ng generate pipe capitalize

This command will create two files inside the src/app folder:

• capitalize.pipe.ts: The implementation of our custom pipe.
• capitalize.pipe.spec.ts: The testing file for our pipe.

3. Implementing the Custom Pipe

Open src/app/capitalize.pipe.ts and implement the logic for the pipe.

// Import necessary modules
import { Pipe, PipeTransform } from '@angular/core';

@Pipe({
  name: 'capitalize' // This is the name of the pipe, used in templates
})
export class CapitalizePipe implements PipeTransform {

  transform(value: string, args?: any[]): string {
    // Check if value is provided and is a string
    if(!value) return value;

    // Convert first letter to uppercase and concatenate with the rest of the string
    const capitalizedValue = value.charAt(0).toUpperCase() + value.slice(1);

    return capitalizedValue;
  }
  
}

In this pipe:

• We take a string as input and capitalize the first letter of that string.
• args: While we aren’t using it here, the args parameter can be useful if you want your pipe to accept additional arguments.

4. Declaring the Pipe

Before using a pipe in our components, we need to declare it in an Angular module. By default, ng generate pipe also updates the module declaration.

Open src/app/app.module.ts.

// Import necessary modules
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { CapitalizePipe } from './capitalize.pipe'; // Import your custom pipe

@NgModule({
  declarations: [
    AppComponent,
    CapitalizePipe // Declare your custom pipe here
  ],
  imports: [
    BrowserModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Make sure to import and declare your custom pipe within the declarations array of your module.

5. Using the Pipe in a Component Template

Now let's use our capitalize pipe in a component template.

Open src/app/app.component.html and add the following content:

<!-- App component HTML -->
<div>
  <h2>Original text:</h2>
  <p>{{ originalText }}</p>

  <h2>Capitalized text using custom pipe:</h2>
  <p>{{ originalText | capitalize }}</p>
</div>

Next, define originalText in your AppComponent.

Open src/app/app.component.ts and update it like so:

// Import necessary modules
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'my-angular-app';
  originalText = 'this text should be capitalized.'
}

6. Test Your Application

Run the following command to serve your application:

ng serve

Navigate to http://localhost:4200/ in your web browser. You should see something like the following:

Original Text:

this text should be capitalized.

Capitalized Text Using Custom Pipe:

This text should be capitalized.

7. Understanding the Transform Method

The transform method in our pipe takes the input value and processes it. In our case, it capitalizes the first letter. Here’s a closer look at it:

transform(value: string, args?: any[]): string {
  if (!value) return value; // Return null if no value is provided
  const firstLetter = value.charAt(0).toUpperCase(); // Capitalize the first letter
  const restOfTheWord = value.slice(1); // Extract the rest of the string
  const capitalizedValue = firstLetter + restOfTheWord; // Concatenate both
  return capitalizedValue; // Return the result
}

For each binding where the pipe is applied, Angular calls the transform method with the bound value (originalText) along with any arguments passed to the pipe. Then, our pipe returns the transformed result back to Angular.

Example with Arguments

If you wish to make your pipe more dynamic, you can pass arguments. For instance, if you want to decide whether to capitalize the entire name or just the first name:

@Pipe({
  name: 'capitalize'
})
export class CapitalizePipe implements PipeTransform {

  transform(value: string, allWords: boolean = false): string {
    if(!value) return value;

    if(allWords) {
      // Capitalize the first letter of every word
      return value.split(' ').map(word => {
        return word.charAt(0).toUpperCase() + word.slice(1);
      }).join(' ');
    } else {
      // Capitalize the first letter only
      return value.charAt(0).toUpperCase() + value.slice(1);
    }
  }

}

Now modify app.component.html to use this updated pipe with argument.

<div>
  <h2>First Letter Capitalized:</h2>
  <p>{{ originalText | capitalize:false }}</p>

  <h2>All Words Capitalized:</h2>
  <p>{{ originalText | capitalize:true }}</p>
</div>

8. Testing Your Pipe (Optional)

It's a good practice to write unit tests for pipes to ensure they are functioning correctly. Open src/app/capitalize.pipe.spec.ts and add test cases.

import { CapitalizePipe } from './capitalize.pipe';

describe('CapitalizePipe', () => {
  let pipe: CapitalizePipe;

  beforeEach(() => {
    pipe = new CapitalizePipe();
  });

  it('should create an instance', () => {
    expect(pipe).toBeTruthy();
  });

  it('should capitalize the first letter only', () => {
    expect(pipe.transform('hello world')).toBe('Hello world');
  });

  it('should capitalize all words when given true as a second argument', () => {
    expect(pipe.transform('hello world', true)).toBe('Hello World');
  });
});

You can now run your tests using the following command:

ng test

Conclusion

Creating custom pipes in Angular can greatly enhance your app's reusability and readability by encapsulating data transformation logic within pipes. By following this guide, you learned how to create, implement, declare, and use a basic custom pipe, as well as how to extend its functionality with parameters and how to write unit tests.