@kirjai blog

Don't overabstract your components

2021-05-19T00:00:00Z

A lot of front end developers nowadays find themselves contributing to component libraries. Component libraries usually consist of components that are reused throughout an application. Some are even used across many different applications. At some point you are tasked with adding a new component. One of the questions you should ask yourself early in the process is - "What should this component's API be?". That is first step in a process known as component API design.

What I mean by "component API" is how consumers of your component - mainly other developers - interact with it. So in the context of React - it's what props this component has.

Component API design takes some careful thought. The right API can reduce the code you have to write and maintain. At the same time, it can make your component more powerful 🤯.

Component as a layer of abstraction

When you are creating a new component - you are, generally, aiming to abstract something away. Whatever you are abstracting ends up being the component's functionality. What it does and the reason why it exists.

As with any abstraction - you are trying to strike a balance. A balance between providing some functionality, and the ability to configure said functionality. That balance is also the reason why you want to keep your abstractions as small as possible. The more functionality you are trying to fit into a single layer of abstraction - the more functionality you might have to make configurable. Something that becomes harder to do the more functionality the abstraction has.

Children prop

When talking about a component's props - it is important not to forget the children prop. In my opinion, the children prop is underutilized in a lot of React components.

Most React developers are familiar with it, at least in the most basic use case:

const MyButton = ({ children }) => <button>{children}</button>

const App = () => <MyButton>Click me!</MyButton>

Rendering the <App /> component will result in the following HTML:

<button>Click me!</button>

That feels pretty natural to do. After all most of HTML is written exactly like that - by nesting elements within other elements. So, the children prop allows your components to be more composable.

<body>
  <header>
    <!-- ... -->
  </header>
  <main>
    <h1>Hello world</h1>
  </main>
</body>

In fact, a lot of common UI elements could benefit from being implemented with the children prop. One of my favorite examples to use is the HTML <select /> element - also referred to as a dropdown.

First, let's establish what the goal of our implementation is. What are we trying to abstract? In the context of a design system - we would, most likely, want to abstract away the specifics of how the <select /> element is styled. Styling itself is beside the point of this post, so I'll resort to styling with CSS classes - nothing fancy.

Basic select implementation

Tasked with implementing a component that wraps the native <select /> element, we might start off with the following:

interface Props {
  options: {
    label: string
    value: string
  }[]
  value: string
  onChange: (value: string) => void
}

const Select = ({ options, onChange, value }: Props) => {
  return (
    <select onChange={onChange} value={value} className="...">
      {options.map(({ label, value }) => (
        <option value={value} className="...">
          {label}
        </option>
      ))}
    </select>
  )
}

That you then use like:

const App = () => <Select
    value={'abc'}
    options={[
      {
        label: 'ABC',
        value: 'abc
      },
      {
        label: 'XYZ',
        value: 'xyz'
      }
    ]}
    onChange={/* ... */}
  />

I have seen a lot implementations of this functionality, similar to the one above. Admittedly, over the years, I have also written few of these myself. This seems like a pretty natural abstraction, so it's easy to reach for it first. Yet, looking at this implementation now, it is too restrictive and not very composable, if you ask me.

One of the main problems with this implementation is that the component tries to do too much. It not only abstracts away the styling - it also abstracts away the HTML via a custom data structure (the options prop). When an abstraction tries to do too much - you might have to add ways to customize different aspects of that abstraction. It is not hard to imagine additional props that might have to be added to the <option /> element in the future. Not to say that there aren't ways of implementing new requirements with this basic approach. However, an alternative implementation that I am proposing sidesteps the issue altogether.

Composable select implementation

import { ReactNode, HTMLProps } from 'react'

interface SelectProps extends HTMLProps<HTMLSelectElement> {
  children: ReactNode
}

const Select = ({ children, ...nativeProps }: SelectProps) => (
  <select {...nativeProps} className="...">
    {children}
  </select>
)

interface OptionProps extends HTMLProps<HTMLOptionElement> {
  children: ReactNode
}

const Option = ({ children, ...nativeProps }: OptionProps) => (
  <option {...nativeProps} className="...">
    {children}
  </option>
)

That you then use similar to a native <select />:

const App = () => (
  <Select value="abc" onChange={/* ... */}>
    <Option value="abc">ABC</Option>
    <Option value="xyz">XYZ</Option>
  </Select>
)

This is a much more flexible, open, and composable API.

Each part of this dropdown is configured close to where it is used;
consumer has full control over which <Select /> and <Option /> implementations to use. For example, you could have different implementations offering different functionality;
consumer can use the full power of JSX to render <Option /> components.

All those benefits with very little code is a win in my book.

Shifting responsibility

There are noticeable differences between the two implementations. One, is that in the composable implementation, some responsibility has been shifted to the consumer. Generally, that is a good thing, but only to an extent. What you want to avoid is having an incomplete abstraction - leaving it up to the consumer to "finish".

For example, let's say that we want to apply a custom CSS class to the <select /> element. You want to do that conditionally, based on a value of another prop. We also want that same class to appear on each <option /> element as well. Leaving it up to the consumer to do that isn't a great idea - it should be handled by our abstraction instead.

However, it might not be immediately clear how to do that, since our <Select /> component doesn't have direct access to the <Option /> components.

Communication between components

There are a few different ways how a parent component can pass values to its children. One of the ways is using the React Context API. It allows parent components to communicate with children components without having a direct reference to them.

Going back to our example - we can wrap all <Select /> component's children in a context provider. <Option /> components can then read values from that context, and use them to perform any work they have to. All without the consumer having to do any extra work. What we'll do is we'll add a new prop to <Select /> called variant. If its value is equal to 'primary' - we'll apply a CSS class 'primary-variant' to the <select /> and <option /> elements.

import { ReactNode, HTMLProps, createContext, useContext } from 'react'

const SelectContext = createContext<{
  additionalClasses: string
}>(null!)

interface SelectProps extends HTMLProps<HTMLSelectElement> {
  children: ReactNode
  variant: string
}

const Select = ({ children, variant, ...nativeProps }: SelectProps) => {
  const additionalClasses = variant === 'primary' ? 'primary-variant' : ''
  return (
    <select {...nativeProps} className={`${additionalClasses} ...`}>
      <SelectContext.Provider value={{ additionalClasses }} >
        {children}
      </SelectContext.Provider>
    </select>
  )
}

interface OptionProps extends HTMLProps<HTMLOptionElement> {
  children: ReactNode
}

const Option = ({ children, ...nativeProps }: OptionProps) => {
  const { additionalClasses } = useContext(SelectProps);
  return (
    <option {...nativeProps} className={`${additionalClasses} ...`}>
      {children}
    </option>
  )
}

Using the React Context API - we were able to pass additionalClasses value from the parent <Select /> component, to its children <Option /> components.

As you can see, we are still able to implement the dropdown UI element as a single unit. Even though it is split across multiple components.

Trade-offs

The composable way of implementing UI elements is not a one-size-fits-all solution. As most things, it comes with some trade-offs.

More opportunity for misconfiguration

This approach shifts some responsibility onto the consumer of a component. With that responsibility, there are more opportunities for a consumer to misconfigure something. However, in my personal view, it should not be that big of a concern.

First, there are often plenty of ways to misconfigure functionality in a non - composable implementation as well. In a composable implementation, configuration is defined closer to where it is used. Meaning that functionality of each <option /> element is defined on the <Option /> component. As opposed to being defined on the parent <Select />, as in the original / basic implementation. Because of that, I would argue that misconfiguration is easier to identify when it occurs.

Second, configuration of UI elements is usually done during development and it is done statically. As opposed to dynamically at runtime. That increases your chances of noticing that something is misconfigured while you are still developing it.

Results in more typing

Similar to the point above - this approach often results in more typing for the consumer. But one way to look at it is that you are trading implicit behaviour for an explicit one. In my experience, explicit implementations are easier to maintain and debug. Additionally, it is important to remember that in case extra typing is a problem - you are free to abstract it away into another layer of abstraction. Composable implementation gives you a foundation. You can build other abstractions on top of it.

In the <Select /> component example, we have decoupled the styling abstraction from a structural abstraction. Now that they are decoupled, you are able to implement either of those abstractions independently of one another. You can then combine them in any way that your use case calls for. That is a strong point for composability - you are able to make that decision for each use case independently. This approach tends to results in smaller and thus more focused abstractions.

Remember, you can always abstract at the consumer level, whereas the more configurable you make an abstraction - the higher the maintenance burden, as that code becomes more ... well, abstract.

Lack of type safety

As far as I know, there is currently no way to effectively type-check children of a component. Meaning that, you cannot type-check that a specific component was provided in the children prop.

Conclusion

My advice is to approach component API design from the perspective of the consumer first. Using that as a starting point for iterating over the API. Having said that, the first API design that comes to your mind might not be the right one. How do you know? Take inspiration from existing component libraries, like Reach UI, Material UI, React Bootstrap, Ant Design to name a few. There is a lot of overlap in problems a lot of us are solving, after all.

Finally, if I find myself rendering components and elements from a configuration object - I take a step back. I re-evaluate whether the problem I am solving could be solved in a more composable and open way.

Using If - Else syntax in Angular

2017-02-27T00:00:00Z

As we approach March 2017, Angular version 4 is almost here. Staying true to the official release schedule the first RC for Angular 4.0 has recently been released. There are many exciting new features, described in the release candidate changelog, like the improved view engine and server side rendering. Among them, is long awaited support for if - else syntax in the template.

What used to be either two separate *ngIf directives or a *ngSwitch, can now become an elegant *ngIf="condition; else templateReference"

// app.component.html
<h1 *ngIf="title; else elseBlock">
  Using If - Else syntax in Angular
  <h1>
    <ng-template #elseBlock>No title</ng-template>
  </h1>
</h1>

As you can see in the snippet above, after the else keyword, we're passing in a template reference variable, that tells Angular which DOM element we want to render when the condition is false, in this case, when the title is falsy. Because elseBlock is just a variable, it can be whatever string you want. This should help simplify your template logic a little.

On top of this, there are more syntax improvements coming in Angular 4.0, like better integration with the async pipe, so keep your eyes open for more.

Accessing child component's class with ViewChild

2017-01-10T00:00:00Z

Most communication between parent and child components in Angular happens with Input and Output bindings. However, in more complex cases you might want a direct access to a child component's class instance. We can achieve exactly that using a powerful ViewChild decorator.

This is especially useful if you have reusable self contained components, like a modal component. Realistically, the parent component will decide when to display the modal. One way to achieve that is by having an isModalOpen boolean property in the parent and pass it as an Input into the ModalComponent.

@Component({
  selector: 'app-modal-parent'
  template: `<app-modal [isOpen]="isModalOpen"></app-modal> <button (click)="isModalOpen = true">Open the modal</button>`
})
export class ModalParentComponent {
  isModalOpen = false;
}

However, that introduces needles state into the parent component, in the form of isModalOpen property.

Let's say our implementation of ModalComponent has an open() and close() methods.

@Component({
  selector: 'app-modal',
  template: `...`,
})
export class ModalComponent {
  open() {
    // logic to open a modal
  }
  close() {
    // logic to close a modal
  }
}

With this implementation, we can call open() from the parent component whenever we need to open the modal. However, this isn't something that can be easily fit into the standard component Inputs and Outputs. Instead, we can use ViewChild to get access to ModalComponents instance inside the ModalParentComponent class and call open() under certain conditions.

`ViewChild`

Inside our parent component, we ask the ViewChild decorator to find an instance of ModalComponent in our component and store it in a property.

@Component({
  //...
  template: `<app-modal></app-modal> <button (click)="openModal()"></button>`,
})
export class ModalParentComponent {
  @ViewChild(ModalComponent) modalInstance
  openModal() {
    this.modalInstance.open()
  }
}

Now, we can control the ModalComponent directly without any state.

Testing Angular forms with dispatchEvent

2016-12-08T00:00:00Z

When testing your Angular applications, make sure you don't forget to test your forms as well. But obviously forms, especially template-driven forms (ngModel), are not something you would write unit tests for. Instead, you want to write shallow component tests, where you get access to native DOM elements that make up your application. Users will interact with your forms by typing, focusing, clicking, etc. so you want to trigger all those events in your tests as well.

Shallow test setup

Here's the setup for writing shallow component tests for MyComponent:

describe('Component', () => {
  let fixture: ComponentFixture<MyComponent>
  let component: MyComponent
  let debugElement: DebugElement

  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [FormsModule],
      declarations: [MyComponent],
    }).compileComponents()
  })

  beforeEach(() => {
    fixture = TestBed.createComponent(MyComponent)
    component = fixture.componentInstance
    debugElement = fixture.debugElement
  })

  // Specs
})

Now, in MyComponent's template we have an input element with an ngModel and a blur event handler.

<input
  id="myInput"
  type="text"
  [(ngModel)]="myInputValue"
  (blur)="someMethod()"
/>

Potential tests that we may write for this input element is testing that the myInputValue binding is valid and that someMethod is called when the input loses focus. In the test setup, we have already defined a debugElement variable that will allow us to query the HTML of our component in order to get ahold of our input element.

// this spec isn't finished yet. no assertion.
it('should bind the input to the correct property', () => {
  // first round of change detection
  fixture.detectChanges()
  // get ahold of the input
  let input = debugElement.query(By.css('#myInput'))
  let inputElement = input.nativeElement
})

Note: it's important to remember to trigger the initial round of change detection before trying to query the debugElement. Component's HTML only gets rendered out, after the first round of change detection.

`.dispatchEvent()`

Now we have access to the native input element, which means we can set its value and assert that the two-way binding between myInputValue in the component class and the input value is valid.

However, simply assigning a string to input's value property is not enough, as that will not trigger a change event. Considering that ngModel acts as an event listener, we need to trigger an "input" event ourselves, using .dispatchEvent. We do that after we've assigned our input a value.

it('should bind the input to the correct property', () => {
  // first round of change detection
  fixture.detectChanges()

  // get ahold of the input
  let input = debugElement.query(By.css('#myInput'))
  let inputElement = input.nativeElement

  //set input value
  inputElement.value = 'test value'
  inputElement.dispatchEvent(new Event('input'))

  expect(component.myInputValue).toBe('test value')
})

Which results in a passing test.

.dispatchEvent has nothing to do with Angular, and is part of Web API. With that in mind, we can now write our second test that asserts that someMethod is called when the input loses focus.

it('should do something on blur', () => {
  spyOn(component, 'someMethod')
  // first round of change detection
  fixture.detectChanges()

  // get ahold of the input
  let input = debugElement.query(By.css('#myInput'))
  let inputElement = input.nativeElement

  //set input value
  inputElement.dispatchEvent(new Event('blur'))

  expect(component.someMethod).toHaveBeenCalled()
})

So as you can see, we can trigger any event listeners on our elements with .dispatchEvent.

Here is a list of all Javascript events.

Code example available here.

Dynamic guard redirects with route data in Angular

2016-11-23T00:00:00Z

If you are using the Angular router within your application, you probably encountered route guards. For those who don't know, guards allow you to restrict specific routes based on certain criteria.

In reality, guards are nothing but services that implement a CanActivate interface. Combine that with custom route data and we can dynamically redirect the user to different routes while reusing the same guards.

import { CanActivate } from '@angular/router'

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(): boolean | Observable<boolean> | Promise<boolean> {
    //...
  }
}

canActivate method needs to return a boolean (which can be wrapped in an Observable or a Promise), which signifies whether a specific route can be navigated to by the user. We can now attach this AuthGuard to any of our routes.

//...

const appRoutes: Routes = [
  {
    path: 'restricted',
    component: RestrictedComponent,
    canActivate: [AuthGuard],
  },
]

With this setup, whenever a user will try navigating to the /restricted route, Angular Router will invoke the canActivate() method on the AuthGuard and depending on whether it returns true or false, user will either be allowed through to the route or not.

Since AuthGuard is just an Angular service, we can inject dependencies into it. We want to only allow authenticated users through to the /restricted route, so we can inject an authentication service into AuthGuard.

//...

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private authService: AuthService) {}

  canActivate(): boolean {
    return this.authService.isUserLoggedIn
  }
}

Redirecting

In case the user is not authenticated and not allowed to view the /restricted route, we would like to navigate him somewhere else. We can manually invoke the navigate() method on the Router.

//...

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private authService: AuthService, private router: Router) {}

  canActivate(): boolean {
    let isUserLoggedIn = this.authService.isUserLoggedIn

    if (!isUserLoggedIn) {
      this.router.navigate(['/unrestricted'])
    }

    return isUserLoggedIn
  }
}

Now, if an unauthenticated user tries to access the /restricted route, he will be redirected to /unrestricted.

Dynamic redirection routes

Realistically, as our application grows, we are likely to start reusing AuthGuard more and more. However, currently, it will always redirect unauthenticated users to /unrestricted. We can make the redirect route dynamic with custom route data.

When defining routes for the application, each route has an optional data property.

//...

const appRoutes: Routes = [
  {
    path: 'restricted',
    component: RestrictedComponent,
    canActivate: [AuthGuard],
    data: {
      authGuardRedirect: '/custom-redirect',
    },
  },
]

Now, in our AuthGuard we can get hold of authGuardRedirect property and pass that into router.navigate() method.

canActivate() method takes in two parameters: ActivatedRouteSnapshot and RouterStateSnapshot. Our custom data can be found on the ActivatedRouteSnapshot.

  //...

  canActivate(routeSnapshot: ActivatedRouteSnapshot): Observable<boolean> {
    let customRedirect = routeSnapshot.data['authGuardRedirect'];
    let isUserLoggedIn = this.authService.isUserLoggedIn;

    if (!isUserLoggedIn) {
      let redirect = !!customRedirect ? customRedirect : '/unrestricted';
      this.router.navigate([redirect]);
    }

    return isUserLoggedIn;
  }

We modified our canActivate logic to redirect the user to the custom redirect route, if present. Otherwise, just redirect to /unrestricted as before.

Our AuthGuard implementation is much more reusable now that we can optionally specify custom redirects for individual routes.

Full code as part of a sample application can be found here.

Testing Angular services with dependencies

2016-11-09T00:00:00Z

Angular services can be tested in a couple of different ways, two most prominent being isolated tests and using the Angular TestBed. However, things get interesting when the service under test has dependencies (injected using Angular's dependency injection).

Isolated tests

In short, tests are considered isolated when a fresh instance of your service class is created before each test, like so:

let serviceUnderTest = new MyService()

Resulting in the following most basic test:

import { MyService } from './my.service'

describe('Service: My: isolated', () => {
  let service: MyService

  beforeEach(() => {
    service = new MyService()
  })

  it('should create an instance', () => {
    expect(service).toBeDefined()
  })
})

You can find more information on isolated service unit tests in the official Angular testing guide.

`TestBed` tests

When writing TestBed tests, you need to define / configure a testing module before each test:

TestBed.configureTestingModule({
  providers: [MyService],
})

The object we pass into the configureTestingModule method follows the same structure as the @NgModule object that we use when defining Angular modules within our application.

The simplest test we can write, if we are using the TestBed would look something like this:

import { MyService } from './my.service'

describe('Service: My: TestBed', () => {
  let service: MyService

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [MyService],
    })

    service = TestBed.get(MyService)
  })

  it('should create an instance', () => {
    expect(service).toBeDefined()
  })
})

As you can see, the TestBed tests require a bit more setup up front, but individual specs (its) are not any different. So why would you ever use the TestBed for your service tests? There are advantages to that approach if your service has dependencies.

Service Dependencies

As soon as you add even one dependency to your service, you need to also add it to your tests. In case of isolated tests, you will need to pass an instance of an injectable dependency class into the constructor of your service instantiation.

let serviceUnderTest = new MyService(new MyServiceDependency())

But this approach would only work if MyServiceDependency does not have any dependencies itself. If it does, you would obviously need to pass them in as well, and so on and so forth. This can get out of hand really quickly.

With this approach it is also harder to mock and stub dependencies, which is something we would definitely prefer to do, as we only want to test a specific service, not the dependencies.

Let's see if we can solve these problems in the TestBed testing approach.

Our TestBed test is failing, with a No Provider for MyServiceDependency! message, which indicates that we are requesting an intance of MyServiceDependency in our MyService class, but we never added MyServiceDependency to any providers of any known modules. Let's look at how we would add a dependency to our TestBed tests in the most basic way.

TestBed.configureTestingModule({
  providers: [MyService, MyServiceDependency],
})

That gets rid of the error, but we are still faced with the same problems as we did with isolated tests:

If MyServiceDependency has dependencies - we would have to add them to the providers as well.
We are injecting an actual instance of MyServiceDependency and not a mock / stub.

The solution to both of these points would be to create a stub of MyServiceDependency and inject it instead of the real MyServiceDependency. Something we can do very easily with the TestBed approach.

Stubbing a dependency

First, we need to create a stub class of our MyServiceDependency class that we will be injecting instead of the real MyServiceDependency class.

class MyServiceDependencyStub {}

Even if the class is blank, i.e. has no methods or properties - we should have no problems injecting it instead of the real service, which we would do in our testing module configuration.

TestBed.configureTestingModule({
  providers: [
    MyService,
    { provide: MyServiceDependency, useClass: MyServiceDependencyStub },
  ],
})

Our test is now passing again.

As you write tests for your service, you will sooner or later encounter some code that uses the dependency, like calling a method or accessing a property on it, which will require you to add it to your stub.

For example, let's say we are writing a test for the following doSomething method on MyService:

//...

@Injectable()
class MyService {
  constructor(private myServiceDependency: MyServiceDependency) {}

  doSomething() {
    this.myServiceDependency.getSomeValue()
  }
}

Potential test for this method would be checking that getSomeValue method is called on myServiceDependency. However, because we are injecting a stub into our testing module, we need to make sure that when doSomething will be called within our tests - getSomeValue method is present on the stub. Simply adding it to our stub will do.

class MyServiceDependencyStub {
  getSomeValue() {}
}

Now, we can easily set up a spy on getSomeValue and assert that it was actually called during the execution of doSomething, resulting in the following full spec file:


import { MyService } from './my.service';
import { MyServiceDependency } from './my-service-dependency';

class MyServiceDependencyStub {
  getSomeValue() {}
}

describe('Service: My: TestBed', () => {
  let service: MyService;
  let myServiceDependency: MyServiceDependency;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        MyService,
        { provide: MyServiceDependency, useClass: MyServiceDependencyStub }
      ]
    });

    service = TestBed.get(MyService);
    myServiceDependency = TestBed.get(MyServiceDependency);
  });

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

  it('should do something'), () => {
    spyOn(myServiceDependency, 'getSomeValue');
    service.doSomething();
    expect(myServiceDependency.getSomeValue).toHaveBeenCalled();
  });
});

In case you ever forget to add a method to a stub, and then try to spy on that method, you will be greeted with an Error: getSomeValue() method does not exist error.

Sample application demonstrating these concepts in a more realistic scenario can be found here

Angular component testing with routerLink and routerOutlet

2016-11-07T00:00:00Z

Official angular testing documentation is a great place to start when it comes to testing your application, and while the docs are great and thorough, it might get a little hard trying to quickly find the info that you are looking for. Especially when things go wrong and you are in the middle of debugging your tests.

One specific subject that I found the docs to be slightly too clever on was testing components that use the routerOutlet and the routerLink.

The problem manifests itself as the following error messages:

'router-outlet' is not a known element

and

Can't bind to 'routerLink' since it isn't a known property

The official documentation explains how you can stub these two directives in your tests, which might be beneficial if you want to test the click events on an element with a routerLink. But more often these error messages prevent the component from rendering and running our other tests for said component. In which case, all you need to do is add the RouterTestingModule to your imports in the testing module configuration, like so:

// app.component.spec.ts

import { RouterTestingModule } from '@angular/router/testing'

TestBed.configureTestingModule({
  imports: [RouterTestingModule],
  declarations: [AppComponent],
})

This solution still allows you to stub either of these directives in the future, if and when you need it.

You can find example application with the code above here

Validation for reactive forms in Angular

2016-09-30T00:00:00Z

As you might know, there are two prominent ways of creating forms in Angular 2+: Template-driven forms and Model-driven or Reactive forms. Template-driven forms definitely have a stronger correlation to how forms are created in AngularJS 1.x, in that they mostly rely on you declaring your form logic in the HTML template. Reactive forms however, are created from a configuration that you specify in your Component class.

In this post we will be going over the Reactive form definition, how to make use of validators as well as writing your own custom validators and providing users with good error messages upon validation.

Set up

Firstly, let's create a simple component and its corresponding template.

// email-form.component.ts
import { Component } from '@angular/core'

@Component({
  selector: 'app-email-form',
  templateUrl: 'email-form.component.html',
})
export class EmailForm {}

<!-- email-form.component.html -->

<form>
  <h2>Email Form</h2>
  <label for="email">Email:</label>
  <input id="email" type="text" />

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

This creates a very basic form that doesn't do anything yet. So the next step is to write up our component and the template.

Enter the `FormBuilder`

The FormBuilder is part of the @angular/forms module that we will be using to create our Reactive form.

In order to use the FormBuilder, we need to import it's type into our component first.

// email-form.component.ts
import { FormBuilder } from '@angular/forms'

Next we need to actually inject the FormBuilder into our component. We do that as we would with any service - in our constructor.

// email-form.component.ts
export class EmailForm {
  constructor(private builder: FormBuilder) {}
}

Now we can use the FormBuilder by referencing it by its the private variable name builder, inside our component. Great! So we can now create our form configuration. Let me first provide an example, which I will explain in more detail afterwards.


// email-form.component.ts
//...

constructor (private builder: FormBuilder) {
  this.emailForm = this.builder.group({})
}

We've created a new property on our class - emailForm and assigned a new group to it, created by the builder. FormBuilder helps us by creating a FormGroup object that will hold our FormControls (more on that later). We will specify individual FormControls that correspond to our input fields by passing them into the this new FormGroup we just created.

However, we assigned the group to a property we haven't defined yet, so at the top of our EmailForm class we need to define the new emailForm property. One thing to note is that the name of the property emailForm can be anything, as with any variable, it is not mapped to anything yet at this point.

// email-form.component.ts
export class EmailForm {
  emailForm: FormGroup

  //...
}

`FormControl` and `formControlName`

FormControl is an Angular class, and we can map instances of this class to form fields. Without FormControls, we can't have validation, or essentially provide any communication between the HTML form and the component class (unless we use ngModel, of course).

So since with reactive forms we specify the form configuration upfront, we need to specify controls that the form will be mapped to. We need to do that inside the form configuration object (our emailForm property) which we are passing to the this.builder.group() function call inside our constructor.


// email-form.component.ts
//...

constructor (private builder: FormBuilder) {
  this.emailForm = this.builder.group({
    email: ['']
  })
}

What exactly happens here? Well, we are passing a FormControl object into our emailForm. As mentioned earlier, a FormControl corresponds to a form field. In our case we have an email input field, and here we are specifying its FormControl object. As with any object, it consists of key-value pairs, and here our new FormControl object has the key of email and value of an array. For now our array value contains just one element, an empty string. This first element in the array represents the default value for our field, and, since we don't want a default value, we are just passing in an empty string.

That's great and all, but how can we map this to our HTML form in the template? There's only two things we need to do for that.

<!-- email-form.component.html -->

<form [formGroup]="emailForm">
  <h2>Email Form</h2>
  <label for="email">Email:</label>
  <input id="email" type="text" formControlName="email" />

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

We have added a new directive formGroup to our form element, and an formControlName to the email input field. The value we give to the formGroup corresponds to the name of our form control group, created by calling builder.group. And the value we give to formControlName is a FormControl instance that we have passed as part of our form configuration object.

Now the form we specified in the component class should be mapped to the HTML form, but how can we make sure that it actually is? We can display the value of the whole form control group in our template using the usual Angular 2+ syntax, below our form.

<!-- email-form.component.html -->

<!-- ... -->

<pre> {{ emailForm.value | json }} </pre>

Try typing into the text field inside your form and see the value of email change inside the emailForm object.

Validation

Now it's time to get creative with our form and make it more useful. Our goal is to make sure that the user has typed something into the input field before submitting the form, i.e. making the field required.

We can use the usual standard HTML validators, like required, minlength etc. inside our HTML, but let's add validators to the form inside our form configuration object.

We will want to use Validators, a class we need to import from @angular/forms module.

// email-form.component.ts

import { FormBuilder, Validators } from '@angular/forms'

//...

In order to make the email input field required, we need to add the 'required' validator to where we are defining a new FormControl - email. The validator we want applied to a control is provided as the second element inside our Control array value:


// email-form.component.ts
//...
constructor(private builder: FormBuilder){
  this.emailForm = this.builder.group({
    email: ['', Validators.required]
  })
}

As you can see, all we need to do to add a validator for a form control is pass it inside the array. But, we can only pass one Validator and one AsyncValidator inside that array. How do we add more validators to the same control then? By using Validators.compose().

I'll show you how to use Validators.compose() a little later on in this post.

We don't need to modify anything inside our template in order to make the validation work. To confirm that our validation is actually working, we can just change the binding inside the <pre> tags in our template, to the following.

<!-- email-form.component.html -->

<pre> {{ emailForm.controls['email'].valid }} </pre>

This also demonstrates one way we can access specific Control objects that are part of our form, from within the template. However we will explore a better and less verbose method a little bit later.

Custom Validators

In a real world use case, you would probably want to validate an email input field with a regular expression or min-length, etc. You could simply use the existing Angular validators for that, however we want to explore how to write our own validators

A custom validator is essentially just a function that returns null if you want the input value to pass validation, or anything else if you want the validation to fail. Let's declare that function next, outside of our constructor.


// email-form.component.ts
//...

checkIfA(fieldControl: FormControl) {
  return fieldControl.value[0] === 'a' ? null : { notA: true };
}

As you can see, the validator function receives an instance of a form control that it going to apply validation to. We can use that instance to access the current value of the control field.

In our example we inspect the current value of the control field and verify it's first letter. If the first letter is a then we return null, indicating that it passed validation. However if the first letter is not an a then we return an error object, which indicates that the validation failed.

The reason for returning an error object for an invalid field is so that we can provide the user with descriptive feedback as to why validation failed. We will explore just how to do that in the next section.

Now that we have our custom validation function, let's apply that to our email control.


// email-form.component.ts
//...

constructor(private builder: FormBuilder) {
  this.emailForm = this.builder.group({
    email: ['', Validators.compose([Validators.required, this.checkIfA])]
  })
}

//...

Instead of passing just Validators.required inside our array for the email control (as the second element to our array), we are now passing the return value of a Validators.compose() function, which takes an array of any validators we want to use. In this case, we want to use both the Validators.required built-in validator, as well as our custom this.checkIfA validator.

Whatever we type into the input field now needs to pass both of these validations for the field to be valid - exactly what we want!

Displaying validation errors

As you might have guessed, we can inspect the .valid property inside our template to check if a field control is valid or not, and conditionally trigger HTML tags depending on the value. Let's explore that in more detail.

In AngularJS 1.x we had a helpful feature - ngMessages that we could use to more easily display helpful messages to the user and explain why their form is invalid. Let's see how we can easily recreate ngMessages in Angular 2+.

In the previous section I provided a little snippet that we can use in our HTML template to see output the validity of our email input field. Admittedly that was quite a verbose way of doing it and - if we want to keep our templates clean and easy to read - it would be far better use the following approach.

Inside our component class we will define a property for our email control, which we can easily access from inside our template.


// email-form.component.ts

//...

constructor(private builder: FormBuilder){
  this.emailForm = this.builder.group({
    email: ['', Validators.compose([Validators.required, this.checkIfA])]
  })

  // This is our new property, which we will access from the template
  this.email = this.emailForm.controls['email'];
}

//...

The idea here is that we write the same verbose way of accessing that control only once, so that we can reference it easily in other places.

However, once again, we are assigning a value to a property on our EmailForm class, that doesn't exist yet. Let's add this property at the top of our class definition.

// email-form.component.ts

export class EmailForm {
  emailForm: ControlGroup
  email: AbstractControl
  //...
}

All we did was create a new property 'email' of type 'AbstractControl', which is an Angular class.

Now we can access the control object for the email field inside our template more easily. Let's replace our previous verbose output with the new one.

<!-- email-form.component.html -->

<!-- before -->

<pre> {{ emailForm.controls['email'].valid }} </pre>

<!-- after -->

<pre> {{ email.valid }} </pre>

It is a little easier to check the validity of our email field now. Let's get on to displaying error messages.

The first thing we'll do is add a paragraph tag <p> with an error message saying that the email field is invalid.

<!-- email-form.component.html -->

<!-- ... -->
<label for="email">Email:</label>
<input id="email" type="text" formControlName="email" />

<p *ngIf="!email.valid">Email is invalid</p>

<!-- ... -->

We are using a structural directive ngIf (provided by Angular 2+) to conditionally display the error message. However, even though it is better than showing nothing, the message by itself is not really descriptive enough. Considering our tricky validation (where the first letter needs to be an a) we definitely need more descriptive error messages. So here's a better solution:

<!-- email-form.component.html -->

<!-- ... -->
<label for="email">Email:</label>
<input id="email" type="text" formControlName="email" />

<div *ngIf="!email.valid">
  <p *ngIf="email.hasError('required')">Email is required</p>
  <p *ngIf="email.hasError('notA')">
    First letter of the email needs to be an a
  </p>
</div>

<!-- ... -->

The error messages are now being triggered conditionally, depending on which validations are failing. At first, both messages are displayed, however try typing anything that doesn't begin with an a and the Email is required error message will disappear, and the other one will stay. That's exactly what we want.

We used a hasError method on our email field control object to check if the email field has specific errors. The notA error that we are checking for in the second error message is the same error that we are passing inside our custom validator that we wrote.

// email-form.component.ts

return fieldControl.value[0] === 'a' ? null : { notA: true } // <-

One final enhancement I would like to add to this form is to not show the errors initially, but to only show them (if appropriate) once the user has interacted with the email field. This is a common practice and is considered a good user experience.

With our current set up, it is very easy to add that feature in.

<!-- email-form.component.html -->

<!-- ... -->

<div *ngIf="!email.valid && email.dirty">
  <p *ngIf="email.hasError('required')">Email is required</p>
  <p *ngIf="email.hasError('notA')">
    First letter of the email needs to be an a
  </p>
</div>
<!-- ... -->

All we need to do is added an && to our ngIf directive, which checks if the email field has been interacted with, or dirty.