|
| 1 | +# Binding dynamic text, properties and attributes |
| 2 | + |
| 3 | +In Angular, a **binding** creates a dynamic connection between a component's template and its data. This connection ensures that changes to the component's data automatically update the rendered template. |
| 4 | + |
| 5 | +## Render dynamic text with text interpolation |
| 6 | + |
| 7 | +You can bind dynamic text in templates with double curly braces, which tells Angular that it is responsible for the expression inside and ensuring it is updated correctly. This is called **text interpolation**. |
| 8 | + |
| 9 | +```angular-ts |
| 10 | +@Component({ |
| 11 | + template: ` |
| 12 | + <p>Your color preference is {{ theme }}.</p> |
| 13 | + `, |
| 14 | + ... |
| 15 | +}) |
| 16 | +export class AppComponent { |
| 17 | + theme = 'dark'; |
| 18 | +} |
| 19 | +``` |
| 20 | + |
| 21 | +In this example, when the snippet is rendered to the page, Angular will replace `{{ theme }}` with `dark`. |
| 22 | + |
| 23 | +```angular-html |
| 24 | +<!-- Rendered Output --> |
| 25 | +<p>Your color preference is dark.</p> |
| 26 | +``` |
| 27 | + |
| 28 | +Bindings that change over time should read values from [signals](/guide/signals). Angular tracks the signals read in the template, and updates the rendered page when those signal values change. |
| 29 | + |
| 30 | +```angular-ts |
| 31 | +@Component({ |
| 32 | + template: ` |
| 33 | + <!-- Does not necessarily update when `welcomeMessage` changes. --> |
| 34 | + <p>{{ welcomeMessage }}</p> |
| 35 | +
|
| 36 | + <p>Your color preference is {{ theme() }}.</p> <!-- Always updates when the value of the `name` signal changes. --> |
| 37 | + ` |
| 38 | + ... |
| 39 | +}) |
| 40 | +export class AppComponent { |
| 41 | + welcomeMessage = "Welcome, enjoy this app that we built for you"; |
| 42 | + theme = signal('dark'); |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +For more details, see the [Signals guide](/guide/signals). |
| 47 | + |
| 48 | +Continuing the theme example, if a user clicks on a button that updates the `theme` signal to `'light'` after the page loads, the page updates accordingly to: |
| 49 | + |
| 50 | +```angular-html |
| 51 | +<!-- Rendered Output --> |
| 52 | +<p>Your color preference is light.</p> |
| 53 | +``` |
| 54 | + |
| 55 | +You can use text interpolation anywhere you would normally write text in HTML. |
| 56 | + |
| 57 | +All expression values are converted to a string. Objects and arrays are converted using the value’s `toString` method. |
| 58 | + |
| 59 | +## Binding dynamic properties and attributes |
| 60 | + |
| 61 | +Angular supports binding dynamic values into object properties and HTML attributes with square brackets. |
| 62 | + |
| 63 | +You can bind to properties on an HTML element's DOM instance, a [component](guide/components) instance, or a [directive](guide/directives) instance. |
| 64 | + |
| 65 | +### Native element properties |
| 66 | + |
| 67 | +Every HTML element has a corresponding DOM representation. For example, each `<button>` HTML element corresponds to an instance of `HTMLButtonElement` in the DOM. In Angular, you use property bindings to set values directly to the DOM representation of the element. |
| 68 | + |
| 69 | +```angular-html |
| 70 | +<!-- Bind the `disabled` property on the button element's DOM object --> |
| 71 | +<button [disabled]="isFormValid()">Save</button> |
| 72 | +``` |
| 73 | + |
| 74 | +In this example, every time `isFormValid` changes, Angular automatically sets the `disabled` property of the `HTMLButtonElement` instance. |
| 75 | + |
| 76 | +### Component and directive properties |
| 77 | + |
| 78 | +When an element is an Angular component, you can use property bindings to set component input properties using the same square bracket syntax. |
| 79 | + |
| 80 | +```angular-html |
| 81 | +<!-- Bind the `value` property on the `MyListbox` component instance. --> |
| 82 | +<my-listbox [value]="mySelection()" /> |
| 83 | +``` |
| 84 | + |
| 85 | +In this example, every time `mySelection` changes, Angular automatically sets the `value` property of the `MyListbox` instance. |
| 86 | + |
| 87 | +You can bind to directive properties as well. |
| 88 | + |
| 89 | +```angular-html |
| 90 | +<!-- Bind to the `ngSrc` property of the `NgOptimizedImage` directive --> |
| 91 | +<img [ngSrc]="profilePhotoUrl()" alt="The current user's profile photo"> |
| 92 | +``` |
| 93 | + |
| 94 | +### Attributes |
| 95 | + |
| 96 | +When you need to set HTML attributes that do not have corresponding DOM properties, such as SVG attributes, you can bind attributes to elements in your template with the `attr.` prefix. |
| 97 | + |
| 98 | +```angular-html |
| 99 | +<!-- Bind the `role` attribute on the `<ul>` element to the component's `listRole` property. --> |
| 100 | +<ul [attr.role]="listRole()"> |
| 101 | +``` |
| 102 | + |
| 103 | +In this example, every time `listRole` changes, Angular automatically sets the `role` attribute of the `<ul>` element by calling `setAttribute`. |
| 104 | + |
| 105 | +If the value of an attribute binding is `null`, Angular removes the attribute by calling `removeAttribute`. |
| 106 | + |
| 107 | +### Text interpolation in properties and attributes |
| 108 | + |
| 109 | +You can also use text interpolation syntax in properties and attributes by using the double curly brace syntax instead of square braces around the property or attribute name. When using this syntax, Angular treats the assignment as a property binding. |
| 110 | + |
| 111 | +```angular-html |
| 112 | +<!-- Binds a value to the `alt` property of the image element's DOM object. --> |
| 113 | +<img src="profile-photo.jpg" alt="Profile photo of {{ firstName() }}" > |
| 114 | +``` |
| 115 | + |
| 116 | +## CSS class and style property bindings |
| 117 | + |
| 118 | +Angular supports additional features for binding CSS classes and CSS style properties to elements. |
| 119 | + |
| 120 | +### CSS classes |
| 121 | + |
| 122 | +You can create a CSS class binding to conditionally add or remove a CSS class on an element based on whether the bound value is [truthy or falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). |
| 123 | + |
| 124 | +```angular-html |
| 125 | +<!-- When `isExpanded` is truthy, add the `expanded` CSS class. --> |
| 126 | +<ul [class.expanded]="isExpanded()"> |
| 127 | +``` |
| 128 | + |
| 129 | +You can also bind directly to the `class` property. Angular accepts three types of value: |
| 130 | + |
| 131 | +| Description of `class` value | TypeScript type | |
| 132 | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | |
| 133 | +| A string containing one or more CSS classes separated by spaces | `string` | |
| 134 | +| An array of CSS class strings | `string[]` | |
| 135 | +| An object where each property name is a CSS class name and each corresponding value determines whether that class is applied to the element, based on truthiness. | `Record<string, any>` | |
| 136 | + |
| 137 | +```angular-ts |
| 138 | +@Component({ |
| 139 | + template: ` |
| 140 | + <ul [class]="listClasses"> ... </ul> |
| 141 | + <section [class]="sectionClasses()"> ... </section> |
| 142 | + <button [class]="buttonClasses()"> ... </button> |
| 143 | + `, |
| 144 | + ... |
| 145 | +}) |
| 146 | +export class UserProfile { |
| 147 | + listClasses = 'full-width outlined'; |
| 148 | + sectionClasses = signal(['expandable', 'elevated']); |
| 149 | + buttonClasses = signal({ |
| 150 | + highlighted: true, |
| 151 | + embiggened: false, |
| 152 | + }); |
| 153 | +} |
| 154 | +``` |
| 155 | + |
| 156 | +The above example renders the following DOM: |
| 157 | + |
| 158 | +```angular-html |
| 159 | +<ul class="full-width outlined"> ... </ul> |
| 160 | +<section class="expandable elevated"> ... </section> |
| 161 | +<button class="highlighted"> ... </button> |
| 162 | +``` |
| 163 | + |
| 164 | +Angular ignores any string values that are not valid CSS class names. |
| 165 | + |
| 166 | +When using static CSS classes, directly binding `class`, and binding specific classes, Angular intelligently combines all of the classes in the rendered result. |
| 167 | + |
| 168 | +```angular-ts |
| 169 | +@Component({ |
| 170 | + template: `<ul class="list" [class]="listType()" [class.expanded]="isExpanded()"> ...`, |
| 171 | + ... |
| 172 | +}) |
| 173 | +export class Listbox { |
| 174 | + listType = signal('box'); |
| 175 | + isExpanded = signal(true); |
| 176 | +} |
| 177 | +``` |
| 178 | + |
| 179 | +In the example above, Angular renders the `ul` element with all three CSS classes. |
| 180 | + |
| 181 | +```angular-html |
| 182 | +<ul class="list box expanded"> |
| 183 | +``` |
| 184 | + |
| 185 | +Angular does not guarantee any specific order of CSS classes on rendered elements. |
| 186 | + |
| 187 | +When binding `class` to an array or an object, Angular compares the previous value to the current value with the triple-equals operator (`===`). You must create a new object or array instance when you modify these values in order for Angular to apply any updates. |
| 188 | + |
| 189 | +If an element has multiple bindings for the same CSS class, Angular resolves collisions by following its style precedence order. |
| 190 | + |
| 191 | +NOTE: Class bindings do not support space-separated class names in a single key. They also don't support mutations on objects as the reference of the binding remains the same. If you need one or the other, use the [ngClass](/api/common/NgClass) directive. |
| 192 | + |
| 193 | +### CSS style properties |
| 194 | + |
| 195 | +You can also bind to CSS style properties directly on an element. |
| 196 | + |
| 197 | +```angular-html |
| 198 | +<!-- Set the CSS `display` property based on the `isExpanded` property. --> |
| 199 | +<section [style.display]="isExpanded() ? 'block' : 'none'"> |
| 200 | +``` |
| 201 | + |
| 202 | +You can further specify units for CSS properties that accept units. |
| 203 | + |
| 204 | +```angular-html |
| 205 | +<!-- Set the CSS `height` property to a pixel value based on the `sectionHeightInPixels` property. --> |
| 206 | +<section [style.height.px]="sectionHeightInPixels()"> |
| 207 | +``` |
| 208 | + |
| 209 | +You can also set multiple style values in one binding. Angular accepts the following types of value: |
| 210 | + |
| 211 | +| Description of `style` value | TypeScript type | |
| 212 | +| ------------------------------------------------------------------------------------------------------------------------- | --------------------- | |
| 213 | +| A string containing zero or more CSS declarations, such as `"display: flex; margin: 8px"`. | `string` | |
| 214 | +| An object where each property name is a CSS property name and each corresponding value is the value of that CSS property. | `Record<string, any>` | |
| 215 | + |
| 216 | +```angular-ts |
| 217 | +@Component({ |
| 218 | + template: ` |
| 219 | + <ul [style]="listStyles()"> ... </ul> |
| 220 | + <section [style]="sectionStyles()"> ... </section> |
| 221 | + `, |
| 222 | + ... |
| 223 | +}) |
| 224 | +export class UserProfile { |
| 225 | + listStyles = signal('display: flex; padding: 8px'); |
| 226 | + sectionStyles = signal({ |
| 227 | + border: '1px solid black', |
| 228 | + 'font-weight': 'bold', |
| 229 | + }); |
| 230 | +} |
| 231 | +``` |
| 232 | + |
| 233 | +The above example renders the following DOM. |
| 234 | + |
| 235 | +```angular-html |
| 236 | +<ul style="display: flex; padding: 8px"> ... </ul> |
| 237 | +<section style="border: 1px solid black; font-weight: bold"> ... </section> |
| 238 | +``` |
| 239 | + |
| 240 | +When binding `style` to an object, Angular compares the previous value to the current value with the triple-equals operator (`===`). You must create a new object instance when you modify these values in order to Angular to apply any updates. |
| 241 | + |
| 242 | +If an element has multiple bindings for the same style property, Angular resolves collisions by following its style precedence order. |
| 243 | + |
| 244 | +## ARIA attributes |
| 245 | + |
| 246 | +Angular supports binding string values to ARIA attributes. |
| 247 | + |
| 248 | +```angular-html |
| 249 | +<button type="button" [aria-label]="actionLabel()"> |
| 250 | + {{ actionLabel() }} |
| 251 | +</button> |
| 252 | +``` |
| 253 | + |
| 254 | +Angular writes the string value to the element’s `aria-label` attribute and removes it when the bound value is `null`. |
| 255 | + |
| 256 | +Some ARIA features expose DOM properties or directive inputs that accept structured values (such as element references). Use standard property bindings for those cases. See the [accessibility guide](best-practices/a11y#aria-attributes-and-properties) for examples and additional guidance. |
0 commit comments