third_party/polymer/components/paper-icon-button/paper-icon-button.html

   1 <!--
   2 Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
   3 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE
   4 The complete set of authors may be found at http://polymer.github.io/AUTHORS
   5 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS
   6 Code distributed by Google as part of the polymer project is also
   7 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS
   8 -->
   9
  10 <!--
  11 @group Paper Elements
  12
  13 Material Design: <a href="http://www.google.com/design/spec/components/buttons.html">Buttons</a>
  14
  15 `paper-icon-button` is a button with an image placed at the center. When the user touches
  16 the button, a ripple effect emanates from the center of the button.
  17
  18 `paper-icon-button` includes a default icon set.  Use `icon` to specify which icon
  19 from the icon set to use.
  20
  21     <paper-icon-button icon="menu"></paper-icon-button>
  22
  23 See [`core-iconset`](#core-iconset) for more information about
  24 how to use a custom icon set.
  25
  26 Example:
  27
  28     <link href="path/to/core-icons/core-icons.html" rel="import">
  29
  30     <paper-icon-button icon="favorite"></paper-icon-button>
  31     <paper-icon-button src="star.png"></paper-icon-button>
  32
  33 Styling
  34 -------
  35
  36 Style the button with CSS as you would a normal DOM element. If you are using the icons
  37 provided by `core-icons`, they will inherit the foreground color of the button.
  38
  39     /* make a red "favorite" button */
  40     <paper-icon-button icon="favorite" style="color: red;"></paper-icon-button>
  41
  42 By default, the ripple is the same color as the foreground at 25% opacity. You may
  43 customize the color using this selector:
  44
  45     /* make #my-button use a blue ripple instead of foreground color */
  46     #my-button::shadow #ripple {
  47       color: blue;
  48     }
  49
  50 The opacity of the ripple is not customizable via CSS.
  51
  52 Accessibility
  53 -------------
  54
  55 The button is accessible by default if you use the `icon` property. By default, the
  56 `aria-label` attribute will be set to the `icon` property. If you use a custom icon,
  57 you should ensure that the `aria-label` attribute is set.
  58
  59     <paper-icon-button src="star.png" aria-label="star"></paper-icon-button>
  60
  61 @element paper-icon-button
  62 @extends paper-button-base
  63 @homepage github.io
  64 -->
  65
  66 <link href="../polymer/polymer.html" rel="import">
  67 <link href="../core-icon/core-icon.html" rel="import">
  68 <link href="../core-icons/core-icons.html" rel="import">
  69 <link href="../paper-button/paper-button-base.html" rel="import">
  70 <link href="../paper-ripple/paper-ripple.html" rel="import">
  71
  72 <polymer-element name="paper-icon-button" extends="paper-button-base" attributes="src icon" role="button">
  73
  74   <template>
  75
  76     <style>
  77       :host {
  78         display: inline-block;
  79         position: relative;
  80         padding: 8px;
  81         outline: none;
  82         -webkit-user-select: none;
  83         -moz-user-select: none;
  84         -ms-user-select: none;
  85         user-select: none;
  86         cursor: pointer;
  87         z-index: 0;
  88       }
  89
  90       :host([disabled]) {
  91         color: #c9c9c9;
  92         pointer-events: none;
  93         cursor: auto;
  94       }
  95
  96       #ripple {
  97         pointer-events: none;
  98         z-index: -1;
  99       }
 100
 101       #icon {
 102         display: block;
 103         pointer-events: none;
 104       }
 105     </style>
 106
 107     <!-- to position to ripple behind the icon -->
 108     <core-icon relative id="icon" src="{{src}}" icon="{{icon}}"></core-icon>
 109
 110   </template>
 111
 112   <script>
 113     Polymer({
 114
 115       publish: {
 116
 117         /**
 118          * The URL of an image for the icon. If the src property is specified,
 119          * the icon property should not be.
 120          *
 121          * @attribute src
 122          * @type string
 123          * @default ''
 124          */
 125         src: '',
 126
 127         /**
 128          * Specifies the icon name or index in the set of icons available in
 129          * the icon's icon set. If the icon property is specified,
 130          * the src property should not be.
 131          *
 132          * @attribute icon
 133          * @type string
 134          * @default ''
 135          */
 136         icon: '',
 137
 138         recenteringTouch: true,
 139         fill: false
 140
 141       },
 142
 143       iconChanged: function(oldIcon) {
 144         var label = this.getAttribute('aria-label');
 145         if (!label || label === oldIcon) {
 146           this.setAttribute('aria-label', this.icon);
 147         }
 148       }
 149
 150     });
 151
 152   </script>
 153
 154 </polymer-element>