diff --git a/.pullapprove.yml b/.pullapprove.yml index 34dd0cba79..171688e2b9 100644 --- a/.pullapprove.yml +++ b/.pullapprove.yml @@ -406,6 +406,7 @@ groups: 'aio/content/guide/structural-directives.md', 'aio/content/examples/structural-directives/**', 'aio/content/guide/svg-in-templates.md', + 'aio/content/guide/style-precedence.md', 'aio/content/images/guide/structural-directives/**', 'aio/content/guide/template-statements.md', 'aio/content/guide/user-input.md', diff --git a/aio/content/examples/attribute-binding/src/app/app.component.html b/aio/content/examples/attribute-binding/src/app/app.component.html index 69f82857fd..7514b871c1 100644 --- a/aio/content/examples/attribute-binding/src/app/app.component.html +++ b/aio/content/examples/attribute-binding/src/app/app.component.html @@ -3,8 +3,10 @@

Attribute binding

+ +

Basic specificity

- -
Some text.
+ +
Some text.
- -
Some text.
+ +
Some text.

Source specificity

- +Some text. - +Some text.

Dynamic vs static

- -
Some text.
+ +
Some text.
- -
Some text.
+ +
Some text.
diff --git a/aio/content/examples/attribute-binding/src/app/app.component.ts b/aio/content/examples/attribute-binding/src/app/app.component.ts index ab35bb09a0..57c9f28718 100644 --- a/aio/content/examples/attribute-binding/src/app/app.component.ts +++ b/aio/content/examples/attribute-binding/src/app/app.component.ts @@ -9,7 +9,7 @@ export class AppComponent { actionName = 'Go for it'; isSpecial = true; canSave = true; - classExpr = 'special clearance'; - styleExpr = 'color: red'; + classExpression = 'special clearance'; + styleExpression = 'color: red'; color = 'blue'; } diff --git a/aio/content/examples/attribute-binding/src/app/comp-with-host-binding.component.ts b/aio/content/examples/attribute-binding/src/app/comp-with-host-binding.component.ts index b93c478f6b..b604e44454 100644 --- a/aio/content/examples/attribute-binding/src/app/comp-with-host-binding.component.ts +++ b/aio/content/examples/attribute-binding/src/app/comp-with-host-binding.component.ts @@ -11,6 +11,9 @@ export class CompWithHostBindingComponent { @HostBinding('style.color') color = 'green'; + // #docregion hostbinding @HostBinding('style.width') width = '200px'; + // #enddocregion hostbinding + } diff --git a/aio/content/guide/attribute-binding.md b/aio/content/guide/attribute-binding.md index c73dbcdb03..899c0813e6 100644 --- a/aio/content/guide/attribute-binding.md +++ b/aio/content/guide/attribute-binding.md @@ -1,6 +1,7 @@ # Attribute, class, and style bindings -The template syntax provides specialized one-way bindings for scenarios less well-suited to property binding. +Attribute binding in Angular helps you set values for attributes directly. +With attribute binding, you can improve accessibility, style your application dynamically, and manage multiple CSS classes or styles simultaneously.
@@ -8,23 +9,36 @@ See the for a working example containing the code
+## Binding to an attribute -## Attribute binding +It is recommended that you set an element property with a [property binding](guide/property-binding) whenever possible. +However, sometimes you don't have an element property to bind. +In those situations, you can use attribute binding. -Set the value of an attribute directly with an **attribute binding**. This is the only exception to the rule that a binding sets a target property and the only binding that creates and sets an attribute. +For example, [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) and +[SVG](https://developer.mozilla.org/en-US/docs/Web/SVG) are purely attributes. +Neither ARIA nor SVG correspond to element properties and don't set element properties. +In these cases, you must use attribute binding because there are no corresponding property targets. -Usually, setting an element property with a [property binding](guide/property-binding) -is preferable to setting the attribute with a string. However, sometimes -there is no element property to bind, so attribute binding is the solution. -Consider the [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) and -[SVG](https://developer.mozilla.org/en-US/docs/Web/SVG). They are purely attributes, don't correspond to element properties, and don't set element properties. In these cases, there are no property targets to bind to. +## Syntax -Attribute binding syntax resembles property binding, but -instead of an element property between brackets, start with the prefix `attr`, -followed by a dot (`.`), and the name of the attribute. -You then set the attribute value, using an expression that resolves to a string, -or remove the attribute when the expression resolves to `null`. +Attribute binding syntax resembles [property binding](guide/property-binding), but instead of an element property between brackets, you precede the name of the attribute with the prefix `attr`, followed by a dot. +Then, you set the attribute value with an expression that resolves to a string. + + + + <p [attr.attribute-you-are-targeting]="expression"></p> + + + +
+ +When the expression resolves to `null`, Angular removes the attribute altogether. + +
+ +## Binding ARIA attributes One of the primary use cases for attribute binding is to set ARIA attributes, as in this example: @@ -33,32 +47,30 @@ is to set ARIA attributes, as in this example: {@a colspan} +## Binding to `colspan` + +Another common use case for attribute binding is with the `colspan` attribute in tables. +Binding to the `colspan` attribute helps you keep your tables programmatically dynamic. +Depending on the amount of data that your application populates a table with, the number of columns that a row spans could change. + +To use attribute binding with the `` to span two columns. +
-#### `colspan` and `colSpan` +Sometimes there are differences between the name of property and an attribute. -Notice the difference between the `colspan` attribute and the `colSpan` property. - -If you wrote something like this: - - - <tr><td colspan="{{1 + 1}}">Three-Four</td></tr> - - -You'd get this error: - - - Template parse errors: - Can't bind to 'colspan' since it isn't a known native property - - -As the message says, the `
`, while `colSpan` with a capital "S" is a property. +When using attribute binding, use `colspan` with a lowercase "s". +For more information on how to bind to the `colSpan` property, see the [`colspan` and `colSpan`](guide/property-binding#colspan) section of [Property Binding](guide/property-binding). @@ -66,28 +78,32 @@ Instead, you'd use property binding and write it like this: {@a class-binding} -## Class binding +## Binding to the `class` attribute -Here's how to set the `class` attribute without a binding in plain HTML: +You can use class binding to add and remove CSS class names from an element's `class` attribute. -```html - -
Some text
-``` +### Binding to a single CSS `class` -You can also add and remove CSS class names from an element's `class` attribute with a **class binding**. +To create a single class binding, use the prefix `class` followed by a dot and the name of the CSS class—for example, `[class.sale]="onSale"`. +Angular adds the class when the bound expression, `onSale` is truthy, and it removes the class when the expression is falsy—with the exception of `undefined`. +See [styling delegation](guide/style-precedence#styling-delegation) for more information. -To create a single class binding, start with the prefix `class` followed by a dot (`.`) and the name of the CSS class (for example, `[class.foo]="hasFoo"`). -Angular adds the class when the bound expression is truthy, and it removes the class when the expression is falsy (with the exception of `undefined`, see [styling delegation](#styling-delegation)). +### Binding to multiple CSS classes -To create a binding to multiple classes, use a generic `[class]` binding without the dot (for example, `[class]="classExpr"`). -The expression can be a space-delimited string of class names, or you can format it as an object with class names as the keys and truthy/falsy expressions as the values. -With object format, Angular will add a class only if its associated value is truthy. +To bind to multiple classes, use `[class]` set to an expression—for example, `[class]="classExpression"`. +The expression can be a space-delimited string of class names, or an object with class names as the keys and truthy or falsy expressions as the values. +With an object format, Angular adds a class only if its associated value is truthy. -It's important to note that with any object-like expression (`object`, `Array`, `Map`, `Set`, etc), the identity of the object must change for the class list to be updated. -Updating the property without changing object identity will have no effect. +
-If there are multiple bindings to the same class name, conflicts are resolved using [styling precedence](#styling-precedence). +With any object-like expression—such as `object`, `Array`, `Map`, or `Set`—the identity of the object must change for Angular to update the class list. +Updating the property without changing object identity has no effect. + +
+ +If there are multiple bindings to the same class name, Angular uses [styling precedence](guide/style-precedence) to determine which binding to use. + +The following table summarizes class binding syntax.
One-Two
` attribute `colspan`: + +1. Specify the `colspan` attribute by using the following syntax: `[attr.colspan]`. +1. Set `[attr.colspan]` equal to an expression. + +In the following example, binds the `colspan` attribute to the expression `1 + 1`. + + + +This binding causes the `
` element does not have a `colspan` property. This is true -because `colspan` is an attribute—`colSpan`, with a capital `S`, is the -corresponding property. Interpolation and property binding can set only *properties*, not attributes. - -Instead, you'd use property binding and write it like this: - - +`colspan` is an attribute of `