{ "id": "guide/binding-syntax", "title": "Binding syntax", "contents": "\n\n\n
\n mode_edit\n
\n\n\n
\n

Binding syntaxlink

\n

Data binding automatically keeps your page up-to-date based on your application's state.\nYou use data binding to specify things such as the source of an image, the state of a button, or data for a particular user.

\n
\n

See the for a working example containing the code snippets in this guide.

\n
\n

Data binding and HTMLlink

\n

Developers can customize HTML by specifying attributes with string values.\nIn the following example, class, src, and disabled modify the <div>, <img>, and <button> elements respectively.

\n\n<div class=\"special\">Plain old HTML</div>\n<img src=\"images/item.png\">\n<button disabled>Save</button>\n\n

Use data binding to control things like the state of a button:

\n\n<!-- Bind button disabled state to `isUnchanged` property -->\n<button [disabled]=\"isUnchanged\">Save</button>\n\n\n

Notice that the binding is to the disabled property of the button's DOM element, not the attribute.\nData binding works with properties of DOM elements, components, and directives, not HTML attributes.

\n\n

HTML attributes and DOM propertieslink

\n

Angular binding distinguishes between HTML attributes and DOM properties.

\n

Attributes initialize DOM properties and you can configure them to modify an element's behavior.\nProperties are features of DOM nodes.

\n\n
\n

Remember that HTML attributes and DOM properties are different things, even when they have the same name.

\n
\n

In Angular, the only role of HTML attributes is to initialize element and directive state.

\n

When you write a data binding, you're dealing exclusively with the DOM properties and events of the target object.

\n

Example 1: an <input>link

\n

When the browser renders <input type=\"text\" value=\"Sarah\">, it creates a\ncorresponding DOM node with a value property and initializes that value to \"Sarah\".

\n\n<input type=\"text\" value=\"Sarah\">\n\n

When the user enters Sally into the <input>, the DOM element value property becomes Sally.\nHowever, if you look at the HTML attribute value using input.getAttribute('value'), you can see that the attribute remains unchanged—it returns \"Sarah\".

\n

The HTML attribute value specifies the initial value; the DOM value property is the current value.

\n

To see attributes versus DOM properties in a functioning app, see the especially for binding syntax.

\n

Example 2: a disabled buttonlink

\n

A button's disabled property is false by default so the button is enabled.

\n

When you add the disabled attribute, you are initializing the button's disabled property to true which disables the button.

\n\n<button disabled>Test Button</button>\n\n

Adding and removing the disabled attribute disables and enables the button.\nHowever, the value of the attribute is irrelevant, which is why you cannot enable a button by writing <button disabled=\"false\">Still Disabled</button>.

\n

To control the state of the button, set the disabled property instead.

\n

Property and attribute comparisonlink

\n

Though you could technically set the [attr.disabled] attribute binding, the values are different in that the property binding must be a boolean value, while its corresponding attribute binding relies on whether the value is null or not.\nConsider the following:

\n\n<input [disabled]=\"condition ? true : false\">\n<input [attr.disabled]=\"condition ? 'disabled' : null\">\n\n

The first line, which uses the disabled property, uses a boolean value.\nThe second line, which uses the disabled attribute checks for null.

\n

Generally, use property binding over attribute binding as a boolean value is easy to read, the syntax is shorter, and a property is more performant.

\n

To see the disabled button example in a functioning application, see the .\nThis example shows you how to toggle the disabled property from the component.

\n

Types of data bindinglink

\n

Angular provides three categories of data binding according to the direction of data flow:

\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n Type\n \n Syntax\n \n Category\n
\n Interpolation
\n Property
\n Attribute
\n Class
\n Style\n
\n \n {{expression}}\n [target]=\"expression\"\n bind-target=\"expression\"\n \n \n One-way
from data source
to view target\n
\n Event\n \n \n (target)=\"statement\"\n on-target=\"statement\"\n \n \n One-way
from view target
to data source\n
\n Two-way\n \n \n [(target)]=\"expression\"\n bindon-target=\"expression\"\n \n \n Two-way\n
\n

Binding types other than interpolation have a target name to the left of the equal sign.\nThe target of a binding is a property or event, which you surround with square brackets, [], parentheses, (), or both, [()].

\n

The binding punctuation of [], (), [()], and the prefix specify the direction of data flow.

\n\n

Place the expression or statement to the right of the equal sign within double quotes, \"\".\nFor more information see Interpolation and Template statements.

\n

Binding types and targetslink

\n

The target of a data binding can be a property, an event, or an attribute name.\nEvery public member of a source directive is automatically available for binding in a template expression or statement.\nThe following table summarizes the targets for the different binding types.

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n Type\n \n Target\n \n Examples\n
\n Property\n \n Element property
\n Component property
\n Directive property\n
\n src, hero, and ngClass in the following:\n \n<img [src]=\"heroImageUrl\">\n<app-hero-detail [hero]=\"currentHero\"></app-hero-detail>\n<div [ngClass]=\"{'special': isSpecial}\"></div>\n\n\n \n
\n Event\n \n Element event
\n Component event
\n Directive event\n
\n click, deleteRequest, and myClick in the following:\n \n<button (click)=\"onSave()\">Save</button>\n<app-hero-detail (deleteRequest)=\"deleteHero()\"></app-hero-detail>\n<div (myClick)=\"clicked=$event\" clickable>click me</div>\n\n\n
\n Two-way\n \n Event and property\n \n \n<input [(ngModel)]=\"name\">\n\n\n
\n Attribute\n \n Attribute\n (the exception)\n \n \n<button [attr.aria-label]=\"help\">help</button>\n\n\n
\n Class\n \n class property\n \n \n<div [class.special]=\"isSpecial\">Special</div>\n\n\n
\n Style\n \n style property\n \n \n<button [style.color]=\"isSpecial ? 'red' : 'green'\">\n\n\n
\n\n \n
\n\n\n" }