+ From inline template with MatIconProvider:
+
+
+
+
Mirrored in RTL:
+
+
@@ -22,6 +30,13 @@
+
+ From inline icon set:
+
+
+
+
+
Ligature from Material Icons font:
home
diff --git a/src/demo-app/icon/icon-demo.ts b/src/demo-app/icon/icon-demo.ts
index bc032395c3eb..f1db8062052e 100644
--- a/src/demo-app/icon/icon-demo.ts
+++ b/src/demo-app/icon/icon-demo.ts
@@ -22,8 +22,47 @@ export class IconDemo {
iconRegistry
.addSvgIcon('thumb-up',
sanitizer.bypassSecurityTrustResourceUrl('/icon/assets/thumbup-icon.svg'))
+ .addSvgIconLiteral('bike',
+ sanitizer.bypassSecurityTrustHtml(BIKE_ICON))
.addSvgIconSetInNamespace('core',
sanitizer.bypassSecurityTrustResourceUrl('/icon/assets/core-icon-set.svg'))
+ .addSvgIconSetLiteralInNamespace('core-inline',
+ sanitizer.bypassSecurityTrustHtml(INLINE_ICON_SET))
.registerFontClassAlias('fontawesome', 'fa');
}
}
+
+const BIKE_ICON = `
+
+`;
+
+const INLINE_ICON_SET = `
+
+`;
diff --git a/src/lib/icon/icon-registry.ts b/src/lib/icon/icon-registry.ts
index 30003f42903b..22f66e61c728 100644
--- a/src/lib/icon/icon-registry.ts
+++ b/src/lib/icon/icon-registry.ts
@@ -16,7 +16,7 @@ import {
SecurityContext,
SkipSelf,
} from '@angular/core';
-import {DomSanitizer, SafeResourceUrl} from '@angular/platform-browser';
+import {DomSanitizer, SafeResourceUrl, SafeHtml} from '@angular/platform-browser';
import {forkJoin, Observable, of as observableOf, throwError as observableThrow} from 'rxjs';
import {catchError, finalize, map, share, tap} from 'rxjs/operators';
@@ -48,18 +48,41 @@ export function getMatIconNoHttpProviderError(): Error {
* @param url URL that was attempted to be sanitized.
* @docs-private
*/
-export function getMatIconFailedToSanitizeError(url: SafeResourceUrl): Error {
+export function getMatIconFailedToSanitizeUrlError(url: SafeResourceUrl): Error {
return Error(`The URL provided to MatIconRegistry was not trusted as a resource URL ` +
`via Angular's DomSanitizer. Attempted URL was "${url}".`);
}
+/**
+ * Returns an exception to be thrown when a HTML string couldn't be sanitized.
+ * @param literal HTML that was attempted to be sanitized.
+ * @docs-private
+ */
+export function getMatIconFailedToSanitizeLiteralError(literal: SafeHtml): Error {
+ return Error(`The literal provided to MatIconRegistry was not trusted as safe HTML by ` +
+ `Angular's DomSanitizer. Attempted literal was "${literal}".`);
+}
+
+
/**
* Configuration for an icon, including the URL and possibly the cached SVG element.
* @docs-private
*/
class SvgIconConfig {
- svgElement: SVGElement | null = null;
- constructor(public url: SafeResourceUrl) { }
+ url: SafeResourceUrl | null;
+ svgElement: SVGElement | null;
+
+ constructor(url: SafeResourceUrl);
+ constructor(svgElement: SVGElement);
+ constructor(data: SafeResourceUrl | SVGElement) {
+ // Note that we can't use `instanceof SVGElement` here,
+ // because it'll break during server-side rendering.
+ if (!!(data as any).nodeName) {
+ this.svgElement = data as SVGElement;
+ } else {
+ this.url = data as SafeResourceUrl;
+ }
+ }
}
/**
@@ -116,6 +139,15 @@ export class MatIconRegistry {
return this.addSvgIconInNamespace('', iconName, url);
}
+ /**
+ * Registers an icon using an HTML string in the default namespace.
+ * @param iconName Name under which the icon should be registered.
+ * @param literal SVG source of the icon.
+ */
+ addSvgIconLiteral(iconName: string, literal: SafeHtml): this {
+ return this.addSvgIconLiteralInNamespace('', iconName, literal);
+ }
+
/**
* Registers an icon by URL in the specified namespace.
* @param namespace Namespace in which the icon should be registered.
@@ -123,9 +155,24 @@ export class MatIconRegistry {
* @param url
*/
addSvgIconInNamespace(namespace: string, iconName: string, url: SafeResourceUrl): this {
- const key = iconKey(namespace, iconName);
- this._svgIconConfigs.set(key, new SvgIconConfig(url));
- return this;
+ return this._addSvgIconConfig(namespace, iconName, new SvgIconConfig(url));
+ }
+
+ /**
+ * Registers an icon using an HTML string in the specified namespace.
+ * @param namespace Namespace in which the icon should be registered.
+ * @param iconName Name under which the icon should be registered.
+ * @param literal SVG source of the icon.
+ */
+ addSvgIconLiteralInNamespace(namespace: string, iconName: string, literal: SafeHtml): this {
+ const sanitizedLiteral = this._sanitizer.sanitize(SecurityContext.HTML, literal);
+
+ if (!sanitizedLiteral) {
+ throw getMatIconFailedToSanitizeLiteralError(literal);
+ }
+
+ const svgElement = this._createSvgElementForSingleIcon(sanitizedLiteral);
+ return this._addSvgIconConfig(namespace, iconName, new SvgIconConfig(svgElement));
}
/**
@@ -136,21 +183,37 @@ export class MatIconRegistry {
return this.addSvgIconSetInNamespace('', url);
}
+ /**
+ * Registers an icon set using an HTML string in the default namespace.
+ * @param literal SVG source of the icon set.
+ */
+ addSvgIconSetLiteral(literal: SafeHtml): this {
+ return this.addSvgIconSetLiteralInNamespace('', literal);
+ }
+
/**
* Registers an icon set by URL in the specified namespace.
* @param namespace Namespace in which to register the icon set.
* @param url
*/
addSvgIconSetInNamespace(namespace: string, url: SafeResourceUrl): this {
- const config = new SvgIconConfig(url);
- const configNamespace = this._iconSetConfigs.get(namespace);
+ return this._addSvgIconSetConfig(namespace, new SvgIconConfig(url));
+ }
- if (configNamespace) {
- configNamespace.push(config);
- } else {
- this._iconSetConfigs.set(namespace, [config]);
+ /**
+ * Registers an icon set using an HTML string in the specified namespace.
+ * @param namespace Namespace in which to register the icon set.
+ * @param literal SVG source of the icon set.
+ */
+ addSvgIconSetLiteralInNamespace(namespace: string, literal: SafeHtml): this {
+ const sanitizedLiteral = this._sanitizer.sanitize(SecurityContext.HTML, literal);
+
+ if (!sanitizedLiteral) {
+ throw getMatIconFailedToSanitizeLiteralError(literal);
}
- return this;
+
+ const svgElement = this._svgElementFromString(sanitizedLiteral);
+ return this._addSvgIconSetConfig(namespace, new SvgIconConfig(svgElement));
}
/**
@@ -202,13 +265,13 @@ export class MatIconRegistry {
* @param safeUrl URL from which to fetch the SVG icon.
*/
getSvgIconFromUrl(safeUrl: SafeResourceUrl): Observable {
- let url = this._sanitizer.sanitize(SecurityContext.RESOURCE_URL, safeUrl);
+ const url = this._sanitizer.sanitize(SecurityContext.RESOURCE_URL, safeUrl);
if (!url) {
- throw getMatIconFailedToSanitizeError(safeUrl);
+ throw getMatIconFailedToSanitizeUrlError(safeUrl);
}
- let cachedIcon = this._cachedIconsByUrl.get(url);
+ const cachedIcon = this._cachedIconsByUrl.get(url);
if (cachedIcon) {
return observableOf(cloneSvg(cachedIcon));
@@ -461,15 +524,19 @@ export class MatIconRegistry {
* Returns an Observable which produces the string contents of the given URL. Results may be
* cached, so future calls with the same URL may not cause another HTTP request.
*/
- private _fetchUrl(safeUrl: SafeResourceUrl): Observable {
+ private _fetchUrl(safeUrl: SafeResourceUrl | null): Observable {
if (!this._httpClient) {
throw getMatIconNoHttpProviderError();
}
+ if (safeUrl == null) {
+ throw Error(`Cannot fetch icon from URL "${safeUrl}".`);
+ }
+
const url = this._sanitizer.sanitize(SecurityContext.RESOURCE_URL, safeUrl);
if (!url) {
- throw getMatIconFailedToSanitizeError(safeUrl);
+ throw getMatIconFailedToSanitizeUrlError(safeUrl);
}
// Store in-progress fetches to avoid sending a duplicate request for a URL when there is
@@ -491,6 +558,34 @@ export class MatIconRegistry {
this._inProgressUrlFetches.set(url, req);
return req;
}
+
+ /**
+ * Registers an icon config by name in the specified namespace.
+ * @param namespace Namespace in which to register the icon config.
+ * @param iconName Name under which to register the config.
+ * @param config Config to be registered.
+ */
+ private _addSvgIconConfig(namespace: string, iconName: string, config: SvgIconConfig): this {
+ this._svgIconConfigs.set(iconKey(namespace, iconName), config);
+ return this;
+ }
+
+ /**
+ * Registers an icon set config in the specified namespace.
+ * @param namespace Namespace in which to register the icon config.
+ * @param config Config to be registered.
+ */
+ private _addSvgIconSetConfig(namespace: string, config: SvgIconConfig): this {
+ const configNamespace = this._iconSetConfigs.get(namespace);
+
+ if (configNamespace) {
+ configNamespace.push(config);
+ } else {
+ this._iconSetConfigs.set(namespace, [config]);
+ }
+
+ return this;
+ }
}
/** @docs-private */
diff --git a/src/lib/icon/icon.md b/src/lib/icon/icon.md
index 21ad287c243f..3936cdeaa6aa 100644
--- a/src/lib/icon/icon.md
+++ b/src/lib/icon/icon.md
@@ -5,8 +5,9 @@ icon fonts and SVG icons, but not bitmap-based formats (png, jpg, etc.).
### Registering icons
-`MatIconRegistry` is an injectable service that allows you to associate icon names with SVG URLs and
-define aliases for CSS font classes. Its methods are discussed below and listed in the API summary.
+`MatIconRegistry` is an injectable service that allows you to associate icon names with SVG URLs,
+HTML strings and to define aliases for CSS font classes. Its methods are discussed below and listed
+in the API summary.
### Font icons with ligatures
@@ -44,19 +45,20 @@ SVG content is the CSS
value. This makes SVG icons by default have the same color as surrounding text, and allows you to
change the color by setting the "color" style on the `mat-icon` element.
-In order to prevent XSS vulnerabilities, any SVG URLs passed to the `MatIconRegistry` must be
-marked as trusted resource URLs by using Angular's `DomSanitizer` service.
+In order to prevent XSS vulnerabilities, any SVG URLs and HTML strings passed to the
+`MatIconRegistry` must be marked as trusted by using Angular's `DomSanitizer` service.
-Also note that all SVG icons are fetched via XmlHttpRequest, and due to the same-origin policy,
-their URLs must be on the same domain as the containing page, or their servers must be configured
-to allow cross-domain access.
+Also note that all SVG icons, registered by URL, are fetched via XmlHttpRequest, and due to the
+same-origin policy, their URLs must be on the same domain as the containing page, or their servers
+must be configured to allow cross-domain access.
#### Named icons
-To associate a name with an icon URL, use the `addSvgIcon` or `addSvgIconInNamespace` methods of
-`MatIconRegistry`. After registering an icon, it can be displayed by setting the `svgIcon` input.
-For an icon in the default namespace, use the name directly. For a non-default namespace, use the
-format `[namespace]:[name]`.
+To associate a name with an icon URL, use the `addSvgIcon`, `addSvgIconInNamespace`,
+`addSvgIconLiteral` or `addSvgIconLiteralInNamespace` methods of `MatIconRegistry`. After
+registering an icon, it can be displayed by setting the `svgIcon` input. For an icon in the
+default namespace, use the name directly. For a non-default namespace, use the format
+`[namespace]:[name]`.
#### Icon sets
@@ -64,9 +66,10 @@ Icon sets allow grouping multiple icons into a single SVG file. This is done by
root `