1<!--
2@license
3Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
4This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
5The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
6The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
7Code distributed by Google as part of the polymer project is also
8subject 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-icon/iron-icon.html">
13<link rel="import" href="../paper-behaviors/paper-inky-focus-behavior.html">
14<link rel="import" href="../paper-styles/default-theme.html">
15
16<!--
17Material design: [Icon toggles](https://www.google.com/design/spec/components/buttons.html#buttons-toggle-buttons)
18
19`paper-icon-button` is a button with an image placed at the center. When the user touches
20the button, a ripple effect emanates from the center of the button.
21
22`paper-icon-button` includes a default icon set.  Use `icon` to specify which icon
23from the icon set to use.
24
25    <paper-icon-button icon="menu"></paper-icon-button>
26
27See [`iron-iconset`](iron-iconset) for more information about
28how to use a custom icon set.
29
30Example:
31
32    <link href="path/to/iron-icons/iron-icons.html" rel="import">
33
34    <paper-icon-button icon="favorite"></paper-icon-button>
35    <paper-icon-button src="star.png"></paper-icon-button>
36
37To use `paper-icon-button` as a link, wrap it in an anchor tag. Since `paper-icon-button`
38will already receive focus, you may want to prevent the anchor tag from receiving focus
39as well by setting its tabindex to -1.
40
41    <a href="https://www.polymer-project.org" tabindex="-1">
42      <paper-icon-button icon="polymer"></paper-icon-button>
43    </a>
44
45### Styling
46
47Style the button with CSS as you would a normal DOM element. If you are using the icons
48provided by `iron-icons`, they will inherit the foreground color of the button.
49
50    /* make a red "favorite" button */
51    <paper-icon-button icon="favorite" style="color: red;"></paper-icon-button>
52
53By default, the ripple is the same color as the foreground at 25% opacity. You may
54customize the color using the `--paper-icon-button-ink-color` custom property.
55
56The following custom properties and mixins are available for styling:
57
58Custom property | Description | Default
59----------------|-------------|----------
60`--paper-icon-button-disabled-text` | The color of the disabled button | `--disabled-text-color`
61`--paper-icon-button-ink-color` | Selected/focus ripple color | `--primary-text-color`
62`--paper-icon-button` | Mixin for a button | `{}`
63`--paper-icon-button-disabled` | Mixin for a disabled button | `{}`
64`--paper-icon-button-hover` | Mixin for button on hover | `{}`
65
66@group Paper Elements
67@element paper-icon-button
68@demo demo/index.html
69-->
70
71<dom-module id="paper-icon-button">
72  <template strip-whitespace>
73    <style>
74      :host {
75        display: inline-block;
76        position: relative;
77        padding: 8px;
78        outline: none;
79        -webkit-user-select: none;
80        -moz-user-select: none;
81        -ms-user-select: none;
82        user-select: none;
83        cursor: pointer;
84        z-index: 0;
85        line-height: 1;
86
87        width: 40px;
88        height: 40px;
89
90        /* NOTE: Both values are needed, since some phones require the value to be `transparent`. */
91        -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
92        -webkit-tap-highlight-color: transparent;
93
94        /* Because of polymer/2558, this style has lower specificity than * */
95        box-sizing: border-box !important;
96
97        @apply(--paper-icon-button);
98      }
99
100      :host #ink {
101        color: var(--paper-icon-button-ink-color, --primary-text-color);
102        opacity: 0.6;
103      }
104
105      :host([disabled]) {
106        color: var(--paper-icon-button-disabled-text, --disabled-text-color);
107        pointer-events: none;
108        cursor: auto;
109
110        @apply(--paper-icon-button-disabled);
111      }
112
113      :host(:hover) {
114        @apply(--paper-icon-button-hover);
115      }
116
117      iron-icon {
118        --iron-icon-width: 100%;
119        --iron-icon-height: 100%;
120      }
121    </style>
122
123    <iron-icon id="icon" src="[[src]]" icon="[[icon]]" alt$="[[alt]]"></iron-icon>
124  </template>
125
126</dom-module>
127<script>
128Polymer({
129  is: 'paper-icon-button',
130
131  hostAttributes: {
132    role: 'button',
133    tabindex: '0'
134  },
135
136  behaviors: [
137    Polymer.PaperInkyFocusBehavior
138  ],
139
140  properties: {
141    /**
142      * The URL of an image for the icon. If the src property is specified,
143      * the icon property should not be.
144      */
145    src: {
146      type: String
147    },
148
149    /**
150      * Specifies the icon name or index in the set of icons available in
151      * the icon's icon set. If the icon property is specified,
152      * the src property should not be.
153      */
154    icon: {
155      type: String
156    },
157
158    /**
159      * Specifies the alternate text for the button, for accessibility.
160      */
161    alt: {
162      type: String,
163      observer: "_altChanged"
164    }
165  },
166
167  _altChanged: function(newValue, oldValue) {
168    var label = this.getAttribute('aria-label');
169
170    // Don't stomp over a user-set aria-label.
171    if (!label || oldValue == label) {
172      this.setAttribute('aria-label', newValue);
173    }
174  }
175});
176</script>
177