third_party/polymer/v1_0/components/iron-icon/iron-icon.html

   1 <!--
   2 @license
   3 Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
   4 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
   5 The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
   6 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
   7 Code distributed by Google as part of the polymer project is also
   8 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
   9 -->
  10
  11 <link rel="import" href="../polymer/polymer.html">
  12 <link rel="import" href="../iron-meta/iron-meta.html">
  13 <link rel="import" href="../iron-flex-layout/iron-flex-layout.html">
  14
  15 <!--
  16
  17 The `iron-icon` element displays an icon. By default an icon renders as a 24px square.
  18
  19 Example using src:
  20
  21     <iron-icon src="star.png"></iron-icon>
  22
  23 Example setting size to 32px x 32px:
  24
  25     <iron-icon class="big" src="big_star.png"></iron-icon>
  26
  27     <style is="custom-style">
  28       .big {
  29         --iron-icon-height: 32px;
  30         --iron-icon-width: 32px;
  31       }
  32     </style>
  33
  34 The iron elements include several sets of icons.
  35 To use the default set of icons, import  `iron-icons.html` and use the `icon` attribute to specify an icon:
  36
  37     &lt;!-- import default iconset and iron-icon --&gt;
  38     <link rel="import" href="/components/iron-icons/iron-icons.html">
  39
  40     <iron-icon icon="menu"></iron-icon>
  41
  42 To use a different built-in set of icons, import  `iron-icons/<iconset>-icons.html`, and
  43 specify the icon as `<iconset>:<icon>`. For example:
  44
  45     &lt;!-- import communication iconset and iron-icon --&gt;
  46     <link rel="import" href="/components/iron-icons/communication-icons.html">
  47
  48     <iron-icon icon="communication:email"></iron-icon>
  49
  50 You can also create custom icon sets of bitmap or SVG icons.
  51
  52 Example of using an icon named `cherry` from a custom iconset with the ID `fruit`:
  53
  54     <iron-icon icon="fruit:cherry"></iron-icon>
  55
  56 See [iron-iconset](#iron-iconset) and [iron-iconset-svg](#iron-iconset-svg) for more information about
  57 how to create a custom iconset.
  58
  59 See [iron-icons](https://elements.polymer-project.org/elements/iron-icons?view=demo:demo/index.html) for the default set of icons.
  60
  61
  62 ### Styling
  63
  64 The following custom properties are available for styling:
  65
  66 Custom property | Description | Default
  67 ----------------|-------------|----------
  68 `--iron-icon-width` | Width of the icon | `24px`
  69 `--iron-icon-height` | Height of the icon | `24px`
  70
  71 @group Iron Elements
  72 @element iron-icon
  73 @demo demo/index.html
  74 @hero hero.svg
  75 @homepage polymer.github.io
  76 -->
  77
  78 <dom-module id="iron-icon">
  79
  80   <style>
  81     :host {
  82       @apply(--layout-inline);
  83       @apply(--layout-center-center);
  84       position: relative;
  85
  86       vertical-align: middle;
  87
  88       fill: currentcolor;
  89
  90       width: var(--iron-icon-width, 24px);
  91       height: var(--iron-icon-height, 24px);
  92     }
  93   </style>
  94
  95   <template>
  96     <iron-meta id="meta" type="iconset"></iron-meta>
  97   </template>
  98
  99   <script>
 100
 101     Polymer({
 102
 103       is: 'iron-icon',
 104
 105       properties: {
 106
 107         /**
 108          * The name of the icon to use. The name should be of the form:
 109          * `iconset_name:icon_name`.
 110          */
 111         icon: {
 112           type: String,
 113           observer: '_iconChanged'
 114         },
 115
 116         /**
 117          * The name of the theme to used, if one is specified by the
 118          * iconset.
 119          */
 120         theme: {
 121           type: String,
 122           observer: '_updateIcon'
 123         },
 124
 125         /**
 126          * If using iron-icon without an iconset, you can set the src to be
 127          * the URL of an individual icon image file. Note that this will take
 128          * precedence over a given icon attribute.
 129          */
 130         src: {
 131           type: String,
 132           observer: '_srcChanged'
 133         }
 134       },
 135
 136       _DEFAULT_ICONSET: 'icons',
 137
 138       _iconChanged: function(icon) {
 139         var parts = (icon || '').split(':');
 140         this._iconName = parts.pop();
 141         this._iconsetName = parts.pop() || this._DEFAULT_ICONSET;
 142         this._updateIcon();
 143       },
 144
 145       _srcChanged: function(src) {
 146         this._updateIcon();
 147       },
 148
 149       _usesIconset: function() {
 150         return this.icon || !this.src;
 151       },
 152
 153       _updateIcon: function() {
 154         if (this._usesIconset()) {
 155           if (this._iconsetName) {
 156             this._iconset = this.$.meta.byKey(this._iconsetName);
 157             if (this._iconset) {
 158               this._iconset.applyIcon(this, this._iconName, this.theme);
 159             } else {
 160               this._warn(this._logf('_updateIcon', 'could not find iconset `'
 161                 + this._iconsetName + '`, did you import the iconset?'));
 162             }
 163           }
 164         } else {
 165           if (!this._img) {
 166             this._img = document.createElement('img');
 167             this._img.style.width = '100%';
 168             this._img.style.height = '100%';
 169           }
 170           this._img.src = this.src;
 171           Polymer.dom(this.root).appendChild(this._img);
 172         }
 173       }
 174
 175     });
 176
 177   </script>
 178
 179 </dom-module>