@HostBinding and @HostListener: what do they do and what are they for?
In my meanderings around the world wide interweb, and now especially the angular.io style docs, I find many references to @HostBinding
and @HostListener
. It seems they are quite fundamental, but unfortunately the documentation for them at the moment is a little sketchy.
Can anyone please explain what they are, how they work and give an example of their usage?
A quick tip that helps me remember what they do -
HostBinding('value') myValue;
is exactly the same as [value]="myValue"
And
HostListener('click') myClick(){ }
is exactly the same as (click)="myClick()"
HostBinding
and HostListener
are written in directives
and the other ones (...)
and [..]
are written inside templates (of components).
Have you checked these official docs?
HostListener - Declares a host listener. Angular will invoke the decorated method when the host element emits the specified event.
@HostListener
- will listen to the event emitted by the host element that's declared with @HostListener
.
HostBinding - Declares a host property binding. Angular automatically checks host property bindings during change detection. If a binding changes, it will update the host element of the directive.
@HostBinding
- will bind the property to the host element, If a binding changes, HostBinding
will update the host element.
NOTE: Both links have been removed recently. The "HostBinding-HostListening" portion of the style guide may be a useful alternative until the links return.
Here's a simple code example to help picture what this means:
DEMO : Here's the demo live in plunker - "A simple example about @HostListener & @HostBinding"
- This example binds a
role
property -- declared with@HostBinding
-- to the host's element- Recall that
role
is an attribute, since we're usingattr.role
. -
<p myDir>
becomes<p mydir="" role="admin">
when you view it in developer tools.
- Recall that
- It then listens to the
onClick
event declared with@HostListener
, attached to the component's host element, changingrole
with each click.- The change when the
<p myDir>
is clicked is that its opening tag changes from<p mydir="" role="admin">
to<p mydir="" role="guest">
and back.
- The change when the
directives.ts
import {Component,HostListener,Directive,HostBinding,Input} from '@angular/core';
@Directive({selector: '[myDir]'})
export class HostDirective {
@HostBinding('attr.role') role = 'admin';
@HostListener('click') onClick() {
this.role= this.role === 'admin' ? 'guest' : 'admin';
}
}
AppComponent.ts
import { Component,ElementRef,ViewChild } from '@angular/core';
import {HostDirective} from './directives';
@Component({
selector: 'my-app',
template:
`
<p myDir>Host Element
<br><br>
We have a (HostListener) listening to this host's <b>click event</b> declared with @HostListener
<br><br>
And we have a (HostBinding) binding <b>the role property</b> to host element declared with @HostBinding
and checking host's property binding updates.
If any property change is found I will update it.
</p>
<div>View this change in the DOM of the host element by opening developer tools,
clicking the host element in the UI.
The role attribute's changes will be visible in the DOM.</div>
`,
directives: [HostDirective]
})
export class AppComponent {}
Here is a basic hover example.
Component's template property:
Template
<!-- attention, we have the c_highlight class -->
<!-- c_highlight is the selector property value of the directive -->
<p class="c_highlight">
Some text.
</p>
And our directive
import {Component,HostListener,Directive,HostBinding} from '@angular/core';
@Directive({
// this directive will work only if the DOM el has the c_highlight class
selector: '.c_highlight'
})
export class HostDirective {
// we could pass lots of thing to the HostBinding function.
// like class.valid or attr.required etc.
@HostBinding('style.backgroundColor') c_colorrr = "red";
@HostListener('mouseenter') c_onEnterrr() {
this.c_colorrr= "blue" ;
}
@HostListener('mouseleave') c_onLeaveee() {
this.c_colorrr = "yellow" ;
}
}
Another nice thing about @HostBinding
is that you can combine it with @Input
if your binding relies directly on an input, eg:
@HostBinding('class.fixed-thing')
@Input()
fixed: boolean;
Summary:
-
@HostBinding
: This decorator binds a class property to a property of the host element. -
@HostListener
: This decorator binds a class method to an event of the host element.
Example:
import { Component, HostListener, HostBinding } from '@angular/core';
@Component({
selector: 'app-root',
template: `<p>This is nice text<p>`,
})
export class AppComponent {
@HostBinding('style.color') color;
@HostListener('click')
onclick() {
this.color = 'blue';
}
}
In the above example the following occurs:
- An event listener is added to the click event which will be fired when a click event occurs anywhere within the component
- The
color
property in ourAppComponent
class is bound to thestyle.color
property on the component. So whenever thecolor
property is updated so will thestyle.color
property of our component - The result will be that whenever someone clicks on the component the color will be updated.
Usage in @Directive
:
Although it can be used on component these decorators are often used in a attribute directives. When used in an @Directive
the host changes the element on which the directive is placed. For example take a look at this component template:
<p p_Dir>some paragraph</p>
Here p_Dir is a directive on the <p>
element. When @HostBinding
or @HostListener
is used within the directive class the host will now refer to the <p>
.