Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hqarroum/gravatar
:guardsman: A promise-based Gravatar client for Node and the browser.
https://github.com/hqarroum/gravatar
gravatar
Last synced: 5 days ago
JSON representation
:guardsman: A promise-based Gravatar client for Node and the browser.
- Host: GitHub
- URL: https://github.com/hqarroum/gravatar
- Owner: HQarroum
- License: mit
- Created: 2015-09-14T09:47:24.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T08:08:02.000Z (almost 2 years ago)
- Last Synced: 2024-11-01T15:52:03.679Z (12 days ago)
- Topics: gravatar
- Language: JavaScript
- Homepage: https://hqarroum.github.io/Gravatar/
- Size: 2.63 MB
- Stars: 7
- Watchers: 3
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Gravatar
> A promise-based Gravatar client for Node and the browser. See [demo here](https://hqarroum.github.io/Gravatar/).
[](https://travis-ci.org/HQarroum/Gravatar)
[](https://codeclimate.com/github/HQarroum/Gravatar)
Current version: **2.0.0**
## Install
```bash
npm install --save gravatar.js
```
## Description
This library covers most of the accessible interfaces exposed by the [Gravatar service](https://en.gravatar.com/site/implement/) and makes them accessible in the context of a browser or a Node.js application. For features requiring a bit more than simply just returning an URL to an image associated with an e-mail address, this module uses asynchronous requests accessible through a promise-based API to resolve remote resources.
## Usage
### Requiring the library
The entry point of the library can be required through different means, each one depending on the environment in which the library is executed.
#### ESM
```javascript
import gravatar from 'gravatar.js';
```
#### Common JS
```javascript
const gravatar = require('gravatar.js');
```
#### Browser (ESM)
```javascript
import gravatar from 'https://unpkg.com/gravatar.js/dist/index.esm.js'
```
#### Browser (UMD)
```javascript
```
### Associating an e-mail with an avatar
To do so, you simply need to pass an e-mail address to the library :
```javascript
const url = gravatar.url('foo@bar');
```
It is also possible to pass several options to this method in order to customize the behaviour of the Gravatar interface :
```javascript
const url = gravatar.url('foo@bar', { defaultIcon: '404', size: 200 });
```
You will find below the list of supported parameters you can pass to the library.
Option key | Description
------------- | -------------
`defaultIcon` | The adopted behaviour when no image is associated with the given e-mail address. The default value is `404`.
`size` | The size of the image in pixels. The default value is *80* pixels.
`rating` | Defines whether to retrieve an avatar given its category, or rating. Take a look [here](https://en.gravatar.com/site/implement/images#rating) for more informations. The default value is `G`.
### Retrieving user profiles
It is possible through the Gravatar API to retrieve a collection of profile objects associated with a user. Using this library it is possible to retrieve this collection using the user e-mail address.
```javascript
// `profiles` is an array of profile objects associated
// with the given e-mail address.
const profiles = await gravatar.profiles('foo@bar');
```
### Resolving an e-mail address
Simply generating an URL given an e-mail address does not mean this URL does actually point to an existing resource. As such, this library provides an interface used to resolve the given e-mail address to a valid avatar URL.
```javascript
// `url` will contain the url to the *main* thumbnail
// associated with the given e-mail address.
const url = await gravatar.resolve('foo@bar');
```
> Similarly to when you generate an URL, you can pass an optional object as a second argument to the `.resolve` method in order to specify how you would like the avatar to be resolved. If the avatar has been resolved, it will be passed as an argument to the success callback.