Skip to content

Commit

Permalink
docs: Improved quick start guide (material-components#4103)
Browse files Browse the repository at this point in the history
  • Loading branch information
@abhiomkar
abhiomkar authored Nov 28, 2018
1 parent 62054f8 commit ccadc6c
Show file tree
Hide file tree
Showing 3 changed files with 87 additions and 97 deletions.
158 changes: 61 additions & 97 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<!-- Required styles for MDC Web -->
<link rel="stylesheet" href="https://unpkg.com/material-components-web@latest/dist/material-components-web.min.css">

<!-- Render textfield component -->
<div class="mdc-text-field">
<input type="text" id="my-text-field" class="mdc-text-field__input">
<label class="mdc-floating-label" for="my-text-field">Hint text</label>
<div class="mdc-line-ripple"></div>
</div>

<!-- Required MDC Web JavaScript library -->
<script src="https://unpkg.com/material-components-web@latest/dist/material-components-web.min.js"></script>
<!-- Instantiate single textfield component rendered in the document -->
<script>
mdc.textField.MDCTextField.attachTo(document.querySelector('.mdc-text-field'));
</script>
```
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
<button class="foo-button mdc-button">
Button
</button>
npm install @material/textfield
```

This will produce a customized Material Design button!
#### HTML

<img src="docs/button.png" alt="Button" width="90" height="36">
Sample usage of text field component. Please see [MDC Textfield](packages/mdc-textfield) component page for more options.

### Include JavaScript for a component
```html
<div class="mdc-text-field">
<input type="text" id="my-text-field" class="mdc-text-field__input">
<label class="mdc-floating-label" for="my-text-field">Hint text</label>
<div class="mdc-line-ripple"></div>
</div>
```

> 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.

<img src="docs/button_with_ripple.png" alt="Button with Ripple" width="90" height="36">
> 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/)
<a href="https://crossbrowsertesting.com/"><img src="test/screenshot/static/images/cbt-logo.png" alt="CrossBrowserTesting logo" width="180" /></a>
17 changes: 17 additions & 0 deletions docs/framework-wrappers.md
View file
Original file line number Diff line number Diff line change
@@ -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).
9 changes: 9 additions & 0 deletions docs/supported-browsers.md
View file
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit ccadc6c

Please sign in to comment.