Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/stevenschobert/instafeed.js

A simple Instagram JavaScript plugin for your website
https://github.com/stevenschobert/instafeed.js

instagram instagram-api javascript

Last synced: about 2 months ago
JSON representation

A simple Instagram JavaScript plugin for your website

Awesome Lists containing this project

README 

        
# Instafeed.js



[![Build Status](https://travis-ci.com/stevenschobert/instafeed.js.svg?branch=master)](https://travis-ci.com/stevenschobert/instafeed.js) [![npm version](https://badge.fury.io/js/instafeed.js.svg)](https://badge.fury.io/js/instafeed.js)



Instafeed.js is a simple way to display your Instagram photos on your website.



Version 2 of Instafeed.js is now available, powered by the new [Instagram Basic Display API](https://developers.facebook.com/docs/instagram-basic-display-api/).



For help upgrading from v1, see the [v2 migration guide](https://github.com/stevenschobert/instafeed.js/wiki/Version-2-migration-guide).



## Hosted Alternative



When I originally wrote Instafeed.js in 2012, I wanted to create an easy way to quickly add your Instagram photos to your website. I like to think I was able to do that, in large part thanks to the public API Instagram had at the time.



Unfortunately, Facebook has made this process a lot more complex than it used to be. The largest problem is that managing API tokens now requires a server-side component, which I can’t provide through Instafeed.js alone.



If you're looking for a turnkey solution that manages tokens for you, or you need more advanced features like hashtag feeds, I recommend looking at [Behold](https://behold.so). It's a paid service, but it has a free tier that will work for smaller projects.



#### → [Check out Behold](https://behold.so)



## Installation



Setting up Instafeed is pretty straight-forward - there are 3 main steps.



 1. Create a Facebook app linked to Instagram, and add yourself as a test user. See [Managing User Tokens](https://github.com/stevenschobert/instafeed.js/wiki/Managing-Access-Tokens).

 2. Create an access token and provide it to an [Instagram Token service](https://github.com/companionstudio/instagram-token-agent)

 3. Add the instafeed.js script to your web page and provide some simple options. See [Basic Usage](https://github.com/stevenschobert/instafeed.js/wiki/Basic-Usage)



```html



```



> Note: Instafeed.js is also compatible with require.js and commonJS exports



## Basic Usage



```html




    var feed = new Instafeed({

      accessToken: 'your-token'

    });

    feed.run();



```



Instafeed will automatically look for a `
` and fill it with linked thumbnails. Of course, you can easily change this behavior using [standard options](#standard-options). Also check out the [advanced options](#advanced-options) for some advanced ways of customizing __Instafeed.js__.



## Requirements



 * A Facebook developer account, and an Instagram account with some media posted to it.

 * A Facebook app linked to your Instagram account, and a token generated through that app.

 * A service to keep your access token fresh



## Options



Here are some of the most commonly used options:



| Key  | Default Value  | Valid types | Description  |

|---|---|---|---|

| `accessToken` | `null` | String, Function | **Required.** The Instagram access token, either as a string, or a function which returns a string |

| `debug` | `false` | Boolean | Set to `true` to display debugging information |

| `filter` | `null` | Function | A function used to exclude images from your results. The function will be given the image data as an argument, and expects the function to return a boolean. |

| `limit` | `null` | Number | Display a maximum of this many posts |

| `sort` | `null` | Function | A custom function to sort the media, rather than the default 'most recent' sorting|

| `target` | `'instafeed'` | String, DOM Element | Either the ID or the DOM element itself where you want to add the images. |

| `template` | `''` | String | A mustache template used to produce HTML for the document. |

| `transform` | `null` | Function | A function used to transform the image data before it is rendered. |



See [Options](https://github.com/stevenschobert/instafeed.js/wiki/Options-Reference) in the wiki for the complete reference.



## Templating



The easiest way to control the way Instafeed.js looks on your website is to use the __template__ option. You can write your own HTML markup and it will be used for every image that Instafeed.js fetches. See [Templating](https://github.com/stevenschobert/instafeed.js/wiki/Templating).



## Changelog



See [CHANGELOG.md](./CHANGELOG.md).