Improve this Doc View Source ngProp

  1. directive in module ng

Overview

The ngProp directive binds an expression to a DOM element property. ngProp allows writing to arbitrary properties by including the property name in the attribute, e.g. ng-prop-value="'my value'" binds 'my value' to the value property.

Usually, it's not necessary to write to properties in AngularJS, as the built-in directives handle the most common use cases (instead of the above example, you would use ngValue).

However, custom elements often use custom properties to hold data, and ngProp can be used to provide input to these custom elements.

Binding to camelCase properties

Since HTML attributes are case-insensitive, camelCase properties like innerHTML must be escaped. AngularJS uses the underscore (_) in front of a character to indicate that it is uppercase, so innerHTML must be written as ng-prop-inner_h_t_m_l="expression" (Note that this is just an example, and for binding HTML ngBindHtml should be used.

Security

Binding expressions to arbitrary properties poses a security risk, as properties like innerHTML can insert potentially dangerous HTML into the application, e.g. script tags that execute malicious code. For this reason, ngProp applies Strict Contextual Escaping with the $sce service. This means vulnerable properties require their content to be "trusted", based on the context of the property. For example, the innerHTML is in the HTML context, and the iframe.src property is in the RESOURCE_URL context, which requires that values written to this property are trusted as a RESOURCE_URL.

This can be set explicitly by calling $sce.trustAs(type, value) on the value that is trusted before passing it to the ng-prop-* directive. There are exist shorthand methods for each context type in the form of $sce.trustAsResourceUrl() et al.

In some cases you can also rely upon automatic sanitization of untrusted values - see below.

Based on the context, other options may exist to mark a value as trusted / configure the behavior of $sce. For example, to restrict the RESOURCE_URL context to specific origins, use the trustedResourceUrlList() and bannedResourceUrlList().

Find out more about the different context types.

HTML Sanitization

By default, $sce will throw an error if it detects untrusted HTML content, and will not bind the content. However, if you include the ngSanitize module, it will try to sanitize the potentially dangerous HTML, e.g. strip non-trusted tags and attributes when binding to innerHTML.

Directive Info

  • This directive executes at priority level 0.

Usage

<ANY ng-prop-propname="expression">
</ANY>

or with uppercase letters in property (e.g. "propName"):

<ANY ng-prop-prop_name="expression">
</ANY>

Examples

Binding to different contexts

Binding to innerHTML with ngSanitize

© 2010–2020 Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
https://code.angularjs.org/1.8.2/docs/api/ng/directive/ngProp