{% include toc.html %}

Material design is a unified system of visual, motion, and interaction design that adapts across different devices. Material design is inspired by tactile materials, such as paper and ink. Material surfaces interact in a shared space. Surfaces can have elevation (z-height) and cast shadows on other surfaces to convey relationships.

{{site.project_title}}'s paper elements collection implements material design for the web. The {{site.project_title}} core elements collection provides a number of unthemed elements that you can use to achieve material design app layouts, transitions, and scrolling effects.

For more detail on the material design philosophy and guidelines, see the Material design specification.

For a sample of the material design patterns in use, see the Topeka sample app.

For quick visual demos of many of the paper elements, see the Paper elements sampler.

The {{site.project_title}} core elements set includes several elements for application layout, including creating toolbars, app bars, tabs, and side nav consistent with the material design guidelines.

See Layout elements for information on using these elements.

To work well with the {{site.project_title}} layout elements, you should make sure other parts of your app follow the same metrics described in the material design spec, such as:

• Baseline grids
• Keylines
• Touch target size

Material design uses icons extensively. {{site.project_title}} provides access to a large variety of scalable, tintable SVG icons using the <core-icon> element and its associated icon sets. Using <core-icon> can be as simple as:

<link rel="import" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fcomponents%2Fcore-icons%2Fcore-icons.html">
<core-icon icon="info"></core-icon>

core-icons.html is a utility import that includes the <core-icon> element and the default icon set, which includes over 150 common icons. Here are a few examples:

For details on using <core-icon> and its relatives, see Using core icons.

The paper elements collection includes a number of material-themed controls for all common areas of your application. The following table shows the common controls.

Dialogs, snackbars and toasts all appear as a separate sheet, overlaying the background. The paper element collection includes two elements.

• A dialog (<paper-dialog>) is a modal window that can include a title, text, action buttons, and other controls.

• A snackbar or toast (<paper-toast>) is a small, transient popup that includes a message and optionally a single action (such as "undo").

Use the <paper-dialog> element to create a dialog. Set a title on a dialog using the heading published property.

You can use any kind of children inside the dialog. For action buttons, add the dismissive or affirmative attributes to place the controls (typically buttons) at the bottom of the dialog:

• dismissive actions, like Cancel, close the dialog and return to the previous screen without making changes. They're displayed on the left.

• affirmative actions, like OK or Save continue a process or confirm a decision. They're displayed on the right.

The following example creates a dialog with two buttons:

<paper-dialog id="dialog" heading="Launch?"
              transition="paper-dialog-transition-bottom">
  <p>This app would like to launch a small, unmanned vehicle
     into space.</p>
  <paper-button dismissive>Cancel</paper-button>
  <paper-button affirmative default>OK</paper-button>
</paper-dialog>

This app would like to launch a small, unmanned vehicle into space.

Cancel OK

Show me the dialog

In this example, the default button has a default attribute. The dialog doesn't apply any special treatment for a default option; you can style it differently using CSS.

Dialogs are hidden by default. Call the dialog's toggle method to show or hide it.

A <paper-toast> element appears at the bottom of the screen or on the lower-left on mobile. Use the text attribute to specify the text to display.

<paper-toast id="toast" text="Your draft has been discarded."></paper-toast>

Show me the snackbar

Like a dialog, a <paper-toast> is hidden by default. Call the element's open method to display it. The toast disappears after a timeout, or can be dismissed by swiping.

When designing your own components or using generic HTML elements such as <div>s, you can add material design effects using the <paper-ripple> and <paper-shadow> elements.

Material responds to input events with an touch ripple effect: an animation that moves out radially from the origin of the event. These effects are built into the paper elements collection:

Show me the ripple

When working with other elements, you can use the <paper-ripple> element to create a touch ripple effect.

To use <paper-ripple>, declare a <paper-ripple> element as a child of the element you want to add the effect to:

<div>
  <paper-ripple fit></paper-ripple>
</div>

Touch the cards and icon below to see ripple effects.

The <paper-ripple> should be position: absolute and sized to fit the parent element. In this example, the fit layout attribute is used to position the ripple appropriately. (See layout attributes for information on fit and other layout attributes.)

You can clip the ripple to a circle by adding the circle class to the ripple's classlist. Circular ripples are used for small buttons used in a grid layout (for example, icon buttons, number pads).

You can set the color of the ripple using the color CSS property.

paper-ripple {
  color: red;
}

When using a paper element, check the element API doc to find the CSS selector to style the ripple. Elements that have a ripple have a <paper-ripple> in the shadow DOM. For example, to style a button:

paper-button::shadow paper-ripple {
  color: blue;
}

To style a checkbox:

paper-checkbox::shadow paper-ripple {
  color: blue;
}

Material has an apparent elevation (z-height) and casts shadows. In {{site.project_title}}, elements can have a z-height between 0 and 5. Material can raise or lower in response to user input.

The paper-elements have shadow effects built-in. For example, a <paper-button> declared with the raised attribute appears raised above the surface it rests on, and raises up when touched.

Raised button

When building your own elements or using standard DOM elements, you can use the <paper-shadow> element to create the appropriate shadow effect.

To apply a shadow to an element, simply add a <paper-shadow> element as a child element of a relatively positioned element. The <paper-shadow> element automatically adds the shadow to its parent element:

 <div style="width: 100px; height: 100px;" relative>
   <paper-shadow z="3"></paper-shadow>
 </div>

You can change the z-height of the target element by setting z on the <paper-shadow> element. Z values range from 0 (no shadow) to 5.

The apparent height of the element (the z-height value) is absolute — that is, an element with a z-height of 3 casts the same size shadow regardless of the z-heights of the background elements. In addition, the z-height does not affect the stacking order of elements. To change stacking order of sibling elements, use the z-index CSS property as usual.

You can apply a shadow to a different element (other than the parent element) by setting the <paper-shadow> element's target property. However, the target must still be an element that accepts children. (For example, you can't add a shadow directly to an <img> element.)

Note: The <paper-shadow> element sets its target to overflow: visible so the shadows are visible outside of the element's borders. If you need to clip inner content, use another container inside the shadowed container. {: .alert .alert-info }

Support for transitions is rapidly evolving. The <core-animated-pages> element displays a single child element at a time, and provides support for sophisticated transitions between two children, or pages.

You can define a set of transitions to be executed when transitioning between pages. To provide visual continuity across transitions, animated pages support hero transitions, where a selected element on the starting page appears to morph into a related element on the ending page. Use hero transitions to link important elements together, while using a simpler transition such as a cross-fade for the remaining elements.

For example transitions, see the <core-animated-pages> demos. The Topeka sample app also demonstrates a number of transitions in context.

The <core-scroll-header-panel> element supports a number of scrolling effects described in the material design spec, including condensing and expanding the toolbar as the user scrolls and hiding or showing the toolbar.

For resizing toolbars, <core-scroll-header-panel> lets you define how to transition the toolbar's contents between states — resizing text, showing or hiding /components, and cross-fading between backgrounds, for example.

See the <core-scroll-header-panel> demos for some examples of the effects possible.