diff --git a/README.md b/README.md index c65cab2618b..f4df6f200ef 100644 --- a/README.md +++ b/README.md @@ -9,140 +9,104 @@ Material Components for the web (MDC Web) helps developers execute [Material Design](https://www.material.io). Developed by a core team of engineers and UX designers at Google, these components enable a reliable development workflow to build beautiful and functional web projects. -Material Components for the web is the successor to [Material Design Lite](https://getmdl.io/), and has 3 high-level goals: - -- Production-ready components consumable in an a-la-carte fashion -- Best-in-class performance and adherence to the [Material Design guidelines](https://material.io/guidelines) -- Seamless integration with other JS frameworks and libraries - - [Material Components for React](https://github.com/material-components/material-components-web-react): MDC Web integration for React (using [foundations/adapters](./docs/integrating-into-frameworks.md#the-advanced-approach-using-foundations-and-adapters)) - - [Material Web Components](https://github.com/material-components/material-components-web-components): MDC Web integration for Web Components (using [vanilla components](./docs/integrating-into-frameworks.md#the-simple-approach-wrapping-mdc-web-vanilla-components)) - - Additional third-party integrations - - [Preact Material Components](https://github.com/prateekbh/preact-material-components) - - [RMWC: React Material Web Components](https://github.com/jamesmfriedman/rmwc) - - [Angular MDC](https://github.com/trimox/angular-mdc-web) - - [Blox Material](https://blox.src.zone/material): Angular Integration Library. - - [Vue MDC Adapter](https://github.com/stasson/vue-mdc-adapter): MDC Web Integration for Vue.js (using [foundations/adapters](./docs/integrating-into-frameworks.md#the-advanced-approach-using-foundations-and-adapters).) - - [Material Components Vue](https://github.com/matsp/material-components-vue): MDC Web Integration for Vue.js (using [vanilla components](./docs/integrating-into-frameworks.md#the-simple-approach-wrapping-mdc-web-vanilla-components)) - - [BalmUI](https://material.balmjs.com/): Next Generation Material UI for Vue.js - - [Ember Material Components](https://github.com/onehilltech/ember-cli-mdc): MDC Web integration for Ember (using [vanilla components](./docs/integrating-into-frameworks.md#the-simple-approach-wrapping-mdc-web-vanilla-components)) - - - More coming soon! Feel free to submit a pull request adding your library to this list, so long as you meet our [criteria](docs/integrating-into-frameworks.md). - MDC Web strives to seamlessly incorporate into a wider range of usage contexts, from simple static websites to complex, JavaScript-heavy applications to hybrid client/server rendering systems. In short, whether you're already heavily invested in another framework or not, it should be easy to incorporate Material Components into your site in a lightweight, idiomatic fashion. -**[Demos](https://material-components.github.io/material-components-web-catalog)** (updated with every release) +Material Components for the web is the successor to [Material Design Lite](https://getmdl.io/). In addition to implementing the [Material Design guidelines](https://material.io/design), it provides more flexible theming customization, not only in terms of color, but also typography, shape, states, and more. It is also specifically [architected](docs/code/architecture.md) for adaptability to various [major web frameworks](docs/framework-wrappers.md). -> Note: Material Components Web follows semver and is still in version 0.x, which means it is regularly subject to +> NOTE: Material Components Web follows semver and is still in version 0.x, which means it is regularly subject to > breaking changes. We typically follow a 2-week release schedule which includes one minor release per month with > breaking changes, and intermediate patch releases with bug fixes. -> A list of changes is always available in the [CHANGELOG](./CHANGELOG.md), -> and a tentative schedule of what we are working on next is available in the [ROADMAP](./ROADMAP.md). - -## Quick start -> Note: This guide assumes you have Node.js and npm installed locally. +## Important links -### Include CSS for a component +- [Getting Started Guide](docs/getting-started.md) +- [Demos](https://material-components.github.io/material-components-web-catalog) +- [MDC Web on other frameworks](docs/framework-wrappers.md) +- [Contributing](CONTRIBUTING.md) +- [Material Design Guidelines](https://material.io/design) (external site) +- [Supported browsers](docs/supported-browsers.md) +- [All Components](packages/) +- [Changelog](./CHANGELOG.md) +- [Roadmap](./ROADMAP.md) -> Note: This guide assumes you have webpack configured to compile Sass into CSS. See the [getting started guide](docs/getting-started.md) for pointers on how to configure webpack. +## Quick start -To include the Sass files for the Material Design button, install the Node dependency: +### Using via CDN +```html + + + + +
+ + +
+
+ + + + + ``` -npm install @material/button -``` - -Then import the Sass files for `@material/button` into your application. You can also use Sass mixins to customize the button: -```scss -@import "@material/button/mdc-button"; +> Please see [quick start demo](https://codepen.io/abhiomkar/pen/gQWarJ) on codepen for full example. -.foo-button { - @include mdc-button-ink-color(teal); - @include mdc-states(teal); -} -``` +### Using NPM -You also need to configure sass-loader to understand the `@material` imports used by MDC Web. Update your `webpack.config.js` by changing `{ loader: 'sass-loader' }` to: +Install textfield node module to your project. -```js -{ - loader: 'sass-loader', - options: { - includePaths: ['./node_modules'] - } -} ``` - -`@material/button` has [documentation](packages/mdc-button/README.md) about the required HTML for a button. Update your application's HTML to include the MDC Button markup, and add the `foo-button` class to the element: - -```html - +npm install @material/textfield ``` -This will produce a customized Material Design button! +#### HTML -Button +Sample usage of text field component. Please see [MDC Textfield](packages/mdc-textfield) component page for more options. -### Include JavaScript for a component +```html +
+ + +
+
+``` -> Note: This guide assumes you have webpack configured to compile ES2015 into JavaScript. See the [getting started guide](docs/getting-started.md) for pointers on how to configure webpack. +#### CSS -To include the ES2015 files for the Material Design ripple, install the dependency: +Load styles required for text field component. -``` -npm install @material/ripple +```scss +@import "@material/textfield/mdc-text-field"; ``` -Then import the ES2015 file for @material/ripple into your application, and initialize an MDCRipple with a DOM element: +#### JavaScript + +Import `MDCTextField` module to instantiate text field component. ```js -import {MDCRipple} from '@material/ripple/index'; -const ripple = new MDCRipple(document.querySelector('.foo-button')); +import {MDCTextField} from '@material/textfield/index'; +const textField = new MDCTextField(document.querySelector('.mdc-text-field')); ``` -> Note: Import `@material/ripple/index` if you wish to transpile MDC Web's ES2015 sources as part of your build process. -> If your build toolchain is configured to only transpile your own sources, import `@material/ripple` instead, which will -> reference the distributed UMD module instead. - -This will produce a Material Design ripple on the button! +This'll initialize text field component on a single `.mdc-text-field` element. -Button with Ripple +> Please see [quick start demo](https://stackblitz.com/edit/mdc-web-quick-start-demo) on stackblitz for full example. -## Useful links - -- [Getting Started Guide](docs/getting-started.md) -- [All Components](packages/) -- [Demos](demos/) -- [Contributing](CONTRIBUTING.md) -- [Material.io](https://www.material.io) (external site) -- [Material Design Guidelines](https://material.io/guidelines) (external site) +> Please see [getting started guide](docs/getting-started.md) for pointers on how to configure webpack to bundle JavaScript & CSS. ## Need help? We're constantly trying to improve our components. If Github Issues don't fit your needs, then please visit us on our [Discord Channel](https://discord.gg/material-components). -## Browser support - -We officially support the last two versions of every major browser. Specifically, we test on the following browsers: - -- **Chrome** on Android, Windows, macOS, and Linux -- **Firefox** on Windows, macOS, and Linux -- **Safari** on iOS and macOS -- **Edge** on Windows -- **IE 11** on Windows - ## Thank you -Fast, reliable [automated screenshot testing](test/screenshot/) is generously provided by: - -[![CrossBrowserTesting logo](test/screenshot/static/images/cbt-logo.png)](https://crossbrowsertesting.com/) - -Free for open source projects! +Third-party services that we use and are thankful to: -Additional continuous integration services courtesy of: +- [Travis CI](https://travis-ci.com/) for CI. +- [Sauce Labs](https://saucelabs.com/) for unit testing. +- [CrossBrowserTesting](https://crossbrowsertesting.com/) for [screenshot testing](test/screenshot/). -- [Travis CI](https://travis-ci.com/) -- [Sauce Labs](https://saucelabs.com/) +CrossBrowserTesting logo diff --git a/docs/framework-wrappers.md b/docs/framework-wrappers.md new file mode 100644 index 00000000000..bb5c8f81511 --- /dev/null +++ b/docs/framework-wrappers.md @@ -0,0 +1,17 @@ +## MDC Web on other frameworks + +Material Components for the web are architected to be adaptable to various major web frameworks. The following wrapper libraries are available: + + - [Material Components for React](https://github.com/material-components/material-components-web-react): MDC Web integration for React (using [foundations/adapters](./integrating-into-frameworks.md#the-advanced-approach-using-foundations-and-adapters)) + - [Material Web Components](https://github.com/material-components/material-components-web-components): MDC Web integration for Web Components (using [vanilla components](./integrating-into-frameworks.md#the-simple-approach-wrapping-mdc-web-vanilla-components)) + - Additional third-party integrations + - [Preact Material Components](https://github.com/prateekbh/preact-material-components) + - [RMWC: React Material Web Components](https://github.com/jamesmfriedman/rmwc) + - [Angular MDC](https://github.com/trimox/angular-mdc-web) + - [Blox Material](https://blox.src.zone/material): Angular Integration Library. + - [Vue MDC Adapter](https://github.com/stasson/vue-mdc-adapter): MDC Web Integration for Vue.js (using [foundations/adapters](./integrating-into-frameworks.md#the-advanced-approach-using-foundations-and-adapters).) + - [Material Components Vue](https://github.com/matsp/material-components-vue): MDC Web Integration for Vue.js (using [vanilla components](./integrating-into-frameworks.md#the-simple-approach-wrapping-mdc-web-vanilla-components)) + - [BalmUI](https://material.balmjs.com/): Next Generation Material UI for Vue.js + - [Ember Material Components](https://github.com/onehilltech/ember-cli-mdc): MDC Web integration for Ember (using [vanilla components](./integrating-into-frameworks.md#the-simple-approach-wrapping-mdc-web-vanilla-components)) + + - More coming soon! Feel free to submit a pull request adding your library to this list, so long as you meet our [criteria](integrating-into-frameworks.md). diff --git a/docs/supported-browsers.md b/docs/supported-browsers.md new file mode 100644 index 00000000000..0ff220ee94a --- /dev/null +++ b/docs/supported-browsers.md @@ -0,0 +1,9 @@ +## MDC Web: Browser support + +We officially support the last two versions of every major browser. Specifically, we test on the following browsers: + +- **Chrome** on Android, Windows, macOS, and Linux +- **Firefox** on Windows, macOS, and Linux +- **Safari** on iOS and macOS +- **Edge** on Windows +- **IE 11** on Windows