WP Instagram Widget


WP Instagram widget is a no fuss WordPress widget to showcase your latest Instagram pics. It does not require you to provide your login details or sign in via oAuth.

The widget is built with the following philosophy:

  • Use sensible and simple markup
  • Provide no styles/css – it is up to you to style the widget to your theme and taste
  • Cache where possible – filters are provided to adjust cache timings
  • Require little setup – avoid oAuth for example

a plugin by Scott Evans


  • Instagram widget on the front end
  • Instagram widget in the theme customizer


To install this plugin:

  1. Upload the wp-instagram-widget folder to the /wp-content/plugins/ directory
  2. Activate the plugin through the ‘Plugins’ menu in WordPress.
  3. That’s it!

Alternatively you can search for the plugin from your WordPress dashboard and install from there.


Installation Instructions

To install this plugin:

  1. Upload the wp-instagram-widget folder to the /wp-content/plugins/ directory
  2. Activate the plugin through the ‘Plugins’ menu in WordPress.
  3. That’s it!

Alternatively you can search for the plugin from your WordPress dashboard and install from there.

Hooks & Filters

The plugin has five filters. The first allows you adjust that cache time for retrieving the images from Instagram:

add_filter('null_instagram_cache_time', 'my_cache_time');

function my_cache_time() {
    return HOUR_IN_SECONDS;

The second allows you to filter video results from the widget:

add_filter('wpiw_images_only', '__return_true');

The rest allow you to add custom classes to the [ul] list container, each list item, link or image:

add_filter( 'wpiw_list_class', 'my_instagram_class' );

add_filter( 'wpiw_item_class', 'my_instagram_class' );
add_filter( 'wpiw_a_class', 'my_instagram_class' );
add_filter( 'wpiw_img_class', 'my_instagram_class' );
add_filter( 'wpiw_linka_class', 'my_instagram_class' );

function my_instagram_class( $classes ) {
    $classes = "instagram-image";
    return $classes;

In version 1.3 you also have two new hooks for adding custom output before and after the widget:


In version 1.4 and above you can also customize the image loop completely by creating a parts/wp-instagram-widget.php file in your theme.

In version 1.9.6 you can now use a filter to change the location of your custom template part: wpiw_template_part.


Will use again

Does the job perfectly! No unnecessary css, js etc. It goes above and beyond without having to go through intragram’s api pairing.

Very grateful for the well documented filters.


No fuss indeed!

Easy to set up and use, great job! The only thing -as others before me have pointed out- is the lack of documentation.

I checked the GitHub repo and it’s basically the same information as the one found here. It’d be nice if you guys put the Wiki to good use 🙂 (eg. you should properly document how to use template files to customize the markup of the widget.)

Nonetheless, great job (again)!

Works but needs a few more styling options.

I use all the time on all my clients’ sites, but I miss some options to customize the layout within the widget itself, I have to use the filters every time and I wonder how can a non-coder user make it look like he/she want easily.

Not working

I’ve installed and activated the plugin, nothing happened.
No documentation available either.

Read all 39 reviews

Contributors & Developers

“WP Instagram Widget” is open source software. The following people have contributed to this plugin.


“WP Instagram Widget” has been translated into 6 locales. Thank you to the translators for their contributions.

Translate “WP Instagram Widget” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.



  • Use image sizes from JSON due to errors loading images


  • Fix hashtag support


  • Ability to track tags / hashtags instead of just usernames (e.g. #cheese)
  • New filter for custom link class
  • Bundle German language (props jensteichert)
  • Other minor fixes and formatting


  • Return more items when using filter for images only


  • Fix double trailing slash on custom text link


  • Trailing slash all URLs to support Instagram app on iOS
  • Support selective refresh in 4.5
  • New filter for wpiw_template_part


  • Another fix for image URL handling, I think we have all the edge cases now!


  • IMPORTANT: You must be on WordPress 4.4 or later to upgrade to this version of the plugin. This fixes a bug with PHP versions < 5.4.7. If you are on a version of WordPress older than 4.4 and you notice images are not loading then I recommend rolling your version of the widget back to this version: https://github.com/scottsweb/wp-instagram-widget/blob/c66550eded59bd51f508f304a85a3e031ac4044c/wp-instagram-widget.php


  • Fix issues introduced in the last version (apologies). Certain CDN URLs are still in use


  • Better handling of all image and video image URLs props @thegallagher


  • Fix bug with some image URLs


  • WordPress.com VIP checked
  • Updated CDN matching to ensure correct image sizes are served at all times
  • Shortened the transient key – should mean we bump into the character limit less often
  • Remove use of extract


  • Apologies for all the recent updates, all good things though!
  • Update plugin text domain ready for translate.wordpress.org
  • Introduce an ‘original’ image size if you want to use non-square originals
  • Introduce new filter for <ul> class wpiw_list_class


  • Bring back image captions
  • Fix small PHP error in 1.7


  • Bring back image sizes
  • Use thumbnails that are square (originals are in the data returned and can be used)
  • Remove @ from usernames


  • Compatibility with 4.3


  • Invalidate old transients


  • Remove null framework support
  • Fix breaking change by Instagram whilst maintaining old style support
  • Remove thumbnail size option


  • Introduce class filters
  • Only set a transient if images are returned
  • Optional template part for complete output control


  • Force lowercase usernames
  • Correct hook name


  • Option to open links in new window
  • Support for video items (with filter to disable this)
  • New actions for adding custom output to the widget
  • Support for https://
  • Correctly escape attributes


  • Change transient name due to data change


  • Better error handling
  • Encode emoji as they cause transient issues


  • Fix issue with Instagram feed
  • Add composer.json


  • Initial release