material-avatar/README.md

simple material design avatars using canvas

<img src="sample.png" align="center" alt="Material Avatar" />

Simple material design avatars using canvas

### Enhanced by [BrowserStack](http://browserstack.com/)

[![Code Climate](https://codeclimate.com/github/hellsan631/material-avatar/badges/gpa.svg)](https://codeclimate.com/github/hellsan631/material-avatar)
[![License](http://img.shields.io/badge/License-MIT-blue.svg)](http://opensource.org/licenses/MIT) 
1.33kb gziped!

====

Material-Avatar is non-opinionated and only has a few small features. It was built to solve a larger problem. _How can I generate a good looking default avatar for a user?_.

I got asked this question once, and there are a lot of other more complex implimentations out there, using bits and bobs to calculate a pixelated image, or grab sets of images from places, or use other web services. I like the way google approached the problem, creating a simple image with initials text.

Material-Avatar uses HTML5 Canvas to fill an element with a random(ized) background color, [which uses this great module to find nice random colors](https://github.com/davidmerfield/randomColor), but has a fall-back just incase you don't include it.

> __Now Supports jQuery!__

### Useage

1. Install using __npm__, __bower__, or __download__.
    ```bash
    npm install --save material-avatar
    bower install --save material-avatar
    ```

    And include your scripts,

    ```html
    <script src="vendor/material-avatar/material-avatar.min.js"></script>
    ```

2. Create a nice div and fill it with a name, or use the attribute __data-name__. _Note, material-avatar defaults to using the size provided by the style of the element on the page_
    ```html
    <div class="default-profile-photo" style="height:200px; width:200px;">
      Paul Gilbert
    </div>
    ```

3. Call __MaterialAvatar__ in somewhere on your page.
    ```html
    <script>
      MaterialAvatar(document.getElementsByClass('default-profile-photo'), options);

      //or use jQuery

      $('.default-profile-photo').materialAvatar(options);
    </script>
    ```

4. Profit.

### Options

> __EffectName:__ "default" _(type)_<br/>
>	Description

1. __shape__ "square" _(string)_ <br/>
Can either be "circle" or "square", and will take that shape (more shapes in future updates!)

2. __randomColor__ _(object)_ <br/>
Settings for using the [randomColor library](https://github.com/davidmerfield/randomColor)

3. __backgroundColor__ _(string)_ <br/>
A hex string for a background color (i.e. '#f12a27'). If not set, one will be chosen at random, or from
a default colorPalette (which can be overridden)

4. __textColor__ _(string)_ <br/>
A hex string for the text color (i.e. '#fff'). If not set, an accessable friendly color will be chosen
based on the background color (either '#222' or '#fff')

5. __colorPalette__ _(array)_ <br/>
An array of color hexes that can will be chosen from randomly as a fallback. Defaults can be found in
the material-avatar.js file.

6. __fontSize__ _(number or function)_ <br/>
An overriding size for font. This can either be a number, measured in px, or a function. If its a function,
it will be sent two arguments, the height of the canvas, and the initials length, which can be used to
return a calculated font size.

7. __fontFamily__ "Arial" _(string)_ <br/>
The chosen font family for generating the canvas initials font.

8. __initials__ _(string)_ <br/>
A string of characters used as the initials for the avatar.

9. __name__ _(string)_ <br/>
In addition to being able to use the data-name attribute, or the innerHtml of an element, you can also pass
a name in the options, which will be broken down into the initial.

[see sample](https://github.com/hellsan631/material-avatar/tree/master/sample) or [the live website](http://hellsan631.github.io/material-avatar/) for some examples.

### Development

If you'd like to develop this little module a bit further, I use a nice gulp build process.

__Get a localhost live-reload web-server running to develop the module__
```
npm install
gulp serve
```

__Before you push your changes, make sure to run the gulp build script__
```
gulp build
```

### License

MIT