1page.title=Using the Material Theme
2
3@jd:body
4
5<div id="tb-wrapper">
6<div id="tb">
7<h2>This lesson teaches you to</h2>
8<ol>
9  <li><a href="#ColorPalette">Customize the Color Palette</a></li>
10  <li><a href="#StatusBar">Customize the Status Bar</a></li>
11  <li><a href="#Inheritance">Theme Individual Views</a></li>
12</ol>
13<h2>You should also read</h2>
14<ul>
15  <li><a href="http://www.google.com/design/spec">Material design specification</a></li>
16  <li><a href="{@docRoot}design/material/index.html">Material design on Android</a></li>
17</ul>
18</div>
19</div>
20
21
22<p>The new material theme provides:</p>
23
24<ul>
25  <li>System widgets that let you set their color palette</li>
26  <li>Touch feedback animations for the system widgets</li>
27  <li>Activity transition animations</li>
28</ul>
29
30<p>You can customize the look of the material theme
31according to your brand identity with a color palette you control. You can tint the action bar and
32the status bar using theme attributes, as shown in <a href="#fig3">Figure 3</a>.</p>
33
34<p>The system widgets have a new design and touch feedback animations. You can customize the
35color palette, the touch feedback animations, and the activity transitions for your app.</p>
36
37<p>The material theme is defined as:</p>
38
39<ul>
40  <li><code>@android:style/Theme.Material</code> (dark version)</li>
41  <li><code>@android:style/Theme.Material.Light</code> (light version)</li>
42  <li><code>@android:style/Theme.Material.Light.DarkActionBar</code></li>
43</ul>
44
45<p>For a list of material styles that you can use, see the API reference for
46{@link android.R.style R.style}.</p>
47
48<!-- two columns, dark/light material theme example -->
49<div style="width:700px;margin-top:25px;margin-bottom:10px">
50<div style="float:left;width:250px;margin-left:40px;margin-right:60px;">
51  <img src="{@docRoot}design/material/images/MaterialDark.png" width="500" height="238">
52  <div style="width:170px;margin:0 auto">
53  <p style="margin-top:8px;font-size:12px"><strong>Figure 1</strong>. Dark material theme</p>
54  </div>
55</div>
56<div style="float:left;width:250px;margin-right:0px;">
57  <img src="{@docRoot}design/material/images/MaterialLight.png" width="500" height="238">
58  <div style="width:170px;margin:0 auto">
59  <p style="margin-top:8px;font-size:12px"><strong>Figure 2</strong>. Light material theme</p>
60  </div>
61</div>
62<br style="clear:left">
63</div>
64
65<p class="note">
66<strong>Note:</strong> The material theme is only available in Android 5.0 (API level 21) and
67above. The <a href="{@docRoot}tools/support-library/features.html#v7">v7 Support Libraries</a>
68provide themes with material design styles for some widgets and support for customizing the color
69palette. For more information, see
70<a href="{@docRoot}training/material/compatibility.html">Maintaining Compatibility</a>.
71</p>
72
73
74<h2 id="ColorPalette">Customize the Color Palette</h2>
75
76<p style="margin-bottom:30px">To customize the theme's base colors to fit your brand, define
77your custom colors using theme attributes when you inherit from the material theme:</p>
78
79<pre>
80&lt;resources>
81  &lt;!-- inherit from the material theme -->
82  &lt;style name="AppTheme" parent="android:Theme.Material">
83    &lt;!-- Main theme colors -->
84    &lt;!--   your app branding color for the app bar -->
85    &lt;item name="android:colorPrimary">@color/primary&lt;/item>
86    &lt;!--   darker variant for the status bar and contextual app bars -->
87    &lt;item name="android:colorPrimaryDark">@color/primary_dark&lt;/item>
88    &lt;!--   theme UI controls like checkboxes and text fields -->
89    &lt;item name="android:colorAccent">@color/accent&lt;/item>
90  &lt;/style>
91&lt;/resources>
92</pre>
93
94<div style="float:right;margin-left:25px;margin-top:20px;margin-bottom:10px" id="fig3">
95<img src="{@docRoot}training/material/images/ThemeColors.png" width="250" height="445"/>
96<p class="img-caption" style="margin-bottom:0px">
97<strong>Figure 3.</strong> Customizing the material theme.</p>
98</div>
99
100
101<h2 id="StatusBar">Customize the Status Bar</h2>
102
103<p>The material theme lets you easily customize the status bar, so you can specify a
104color that fits your brand and provides enough contrast to show the white status icons. To
105set a custom color for the status bar, use the <code>android:statusBarColor</code> attribute when
106you extend the material theme. By default, <code>android:statusBarColor</code> inherits the
107value of <code>android:colorPrimaryDark</code>.</p>
108
109<p>You can also draw behind the status bar yourself. For example, if you want to show
110the status bar transparently over a photo, with a subtle dark gradient to ensure the white
111status icons are visible. To do so, set the <code>android:statusBarColor</code> attribute to
112<code>&#64;android:color/transparent</code> and adjust the window flags as required. You can
113also use the {@link android.view.Window#setStatusBarColor Window.setStatusBarColor()} method for
114animations or fading.</p>
115
116<p class="note">
117<strong>Note:</strong> The status bar should almost always have a clear delineation from the
118primary toolbar, except for cases where you show edge-to-edge rich imagery or media content behind
119these bars and when you use a gradient to ensure that the icons are still visible.
120</p>
121
122<p>When you customize the navigation and status bars, either make them both transparent or modify
123only the status bar. The navigation bar should remain black in all other cases.</p>
124
125
126<h2 id="Inheritance">Theme Individual Views</h3>
127
128<p>Elements in XML layout definitions can specify the <code>android:theme</code> attribute,
129which references a theme resource. This attribute modifies the theme for the element and any
130child elements, which is useful for altering theme color palettes in a specific portion
131of an interface.</p>
132