Material Components for the Web

Web

Integrating MDC-Web into Frameworks

MDC-Web was designed to be integrated as easily as possible into any and all web frameworks. This document will walk you through strategies for integrating components into various types of frameworks.

Examples

Our framework-examples directory contains sample applications built in various frameworks, such as react and angular2 that show how to wrap our components. If there’s an example framework you’d like to see, or if you’re a framework author who wants to provide an example, please consider letting us know and we’ll work with you to have it contributed!

Approaches

There are two approaches you can take for integrating our components into frameworks: the simple approach and the advanced approach. Both have their benefits and drawbacks, and are explained below.

The Simple Approach: Wrapping MDC-Web vanilla components.

The easiest way to integrate MDC-Web into frameworks is to use our vanilla components directly. This works well for frameworks which assume they will be executed within the context of a browser, such as angular v1, backbone.js, or even things such as jQuery plugins.

The simple approach can be outlined as follows:

  1. Include the Component’s CSS on the page any way you wish
  2. Create a wrapper component for your framework of choice, and add a property which will be set to the value of the MDC-Web Component. We’ll call this mdcComponent.
  3. When the wrapper component is initialized (e.g. it is instantiated and attached to the DOM), instantiate the MDC-Web component with a root element, and assign it to the mdcComponent property.
  4. When the wrapper component is destroyed (e.g. it is unbound and detached from the DOM), call mdcComponent.destroy() to clean up the MDC-Web component.

This general approach will work for almost all basic use-cases. For an example of this approach, check out this plunk which shows how to wrap our textfield within an angular v1 component, as well as our button (with a ripple) within an attribute directive.

Note that this approach will also work for custom elements. Use connectedCallback for initialization and disconnectedCallback for destruction.

The Advanced Approach: Using foundations and adapters

Many modern front-end libraries/frameworks, such as react and angular2, wind up targeting more than just a web browser. For these frameworks - and for some highly advanced application architectures - a more robust approach is required. We provide foundations and adapters to accommodate this use case.

If you are interested in wrapping our components using foundations/adapters, you should first read through our architecture overview in order to familiarize yourself with the general concepts behind them.

Every component comes with a complementary foundation class, which is usually called MDCComponentFoundation, where MDCComponent is the name of a component. For example, we have an MDCSimpleMenuFoundation that is used by our MDCSimpleMenu component, and which are both exported publicly.

In order to implement a component via a foundation, take the following steps:

  1. Include the component’s CSS on the page any way you wish
  2. Add an instance property to your component which will be set to the proper foundation class. We’ll calls this mdcFoundation.
  3. Instantiate a foundation class, passing it a properly configured adapter as an argument
  4. When your component is initialized, call mdcFoundation.init()
  5. When your component is destroyed, call mdcFoundation.destroy()

Because of the nature of our components, some of the adapter APIs can be quite complex. However, we are working as hard as we can to make writing adapters as easy and predictable as possible:

Our framework-examples directory contains sample code for various frameworks showing how adapters can be implemented. We encourage you to take a look through those applications to get a sense of how you might build your own.

Please file an issue with us if there are certain snags you’ve ran into trying to implement an adapter, or if you feel that we can provide better guidance on a particular problem. This is definitely something we want to know about.