JavaScript API

Spotlight offers a basic JavaScript API that allows your own JavaScript code to initialize, interact and modify your Instagram feeds.

The API is accessible from the SpotlightInstagram global object variable. This object consists of 3 properties:

{
    // a list containing all of the feeds on the page
    instances: [],
    // a function that initializes a single feed on the page
    feed: (element, options) => void,
    // a function that initializes _all_ the feeds on the page
    init: (options) => void,
}

Initializing feeds

The SpotlightInstagram.init() function is automatically called by Spotlight when the page loads. If your page content changes or is re-rendered, such as if you are using an AJAX-powered theme, you may need to re-initalize the Spotlight feeds on the page.

Generally, calling the SpotlightInstagram.init() function is enough. If you want to be more granular about which feeds to initialize, you can use the SpotlightInstagram.feed() function. This function requires the HTML element of the feed as argument - this is the element that has the "spotlight-instagram-feed" HTML class.

// Example: only initialize the second feed on the page
const elements = document.getElementsByClassName("spotlight-instagram-feed");
const secondFeed = elements[1];
SpotlightInstagram.feed(secondFeed);

Both the SpotlightInstagram.feed() and SpotlightInstagram.init() functions accept an options object argument for passing additional options to Spotlight. The currently available options are:

{
    // If true, suppresses initialization warnings in the browser console
    silent: boolean
}

Instances

The SpotlightInstagram.instances list consists of App objects. Each App represents a single feed, and is a JS object that looks something like this:

{
    // A unique key for this App instance
    key: string,
    // The HTML element that the feed app is mounted on
    mount: HTMLElement,
    // A DI service container
    container: Container,
    // A list of modules
    modules: Modules[]
}

Don't concern yourself too much about what the container and modules are - all you really need to know is that the container is used to obtain a Feed object, like so:

// Get the app instance
const instance = SpotlightInstagram.instances[0];
// Get the feed object from the instance
const feed = instance.container.get("front/feed");

Feed API

Feeds offer quite an extensive API. Below are some of the most common things you may wish to do with your feed. To see what else you could do with the feed, we recommend copying and pasting the below one-liner into your browser's console and inspecting the contents of the feed object.

const feed = SpotlightInstagram.instances[0].container.get("front/feed");

Get total number of posts

Use the feed.totalMedia property gives the total number of posts that the feed can show. This also includes posts that have not yet been loaded into the feed. Useful if you want to know how many posts you can load before using feed.loadMore().

Load more posts

Call this method to load more posts in the feed. This is equivalent to clicking the "Load more" button in the feed.

feed.loadMore()

Load specific posts

Call this method to load a specific set of posts in the feed.

// Usage:
feed.loadMedia(from, number, reset);

// Add 8 posts to the feed, skipping the first 3 posts
feed.loadMedia(3, 8, false);

// Replace the feed's posts with the last 3 posts
feed.loadMedia(feed.totalMedia - 3, 3, true);

Reload the feed

Call this method to reload the posts in the feed. This will also reset any posts that were loaded in later using the "Load more" button or the feed.loadMore() method.

feed.reload()

Disable "Load More"

You can disable the feed's "Load more" option by setting the canLoadMore property to false:

feed.canLoadMore = false

Get the posts/stories

The below properties give you access to the posts and stories that are currently shown in the feed.

feed.media
feed.stories

Change the feed's options

The feed's options are saved in the feed.options object. Changes made to this object will immediately be reflected in the feed.

feed.options.customBioText = "Custom bio!"
feed.options.bgColor = {r: 255, g: 0, b: 0, a: 1}
feed.options.feedPadding = {desktop: 100, tablet: 10, phone: 0}

Some notes about option values:

Color options need to be set to an object that consists of 4 properties: r, g, b and a which represent red, green, blue and alpha respectively. The order of the properties is not important. The r, g and b properties must be set to a number between 0 and 255, while the a property must be a number between 0 (transparent) and 1 (opaque).

Many of the options are responsive. This means that instead of being set to a single value, they must be set to an object that provides values for desktop devices, tablet devices and phone devices. If you only want to set a single value, you can omit the tablet and phone values and only provide the desktop value. We recommend logging the feed's options to see which of them are responsive.

// Set different text sizes for different devices
feed.options.textSize = {desktop: 14, tablet: 16, phone: 20}

// Set a single text size for all devices
feed.options.textSize = {desktop: 15}

Some options won't have any affect on the feed at all. These are typically options that are only used by the server and not by the feed, such as moderation, promotion and filtering options. Additionally, we don't recommend changing the accounts, tagged and hashtags options, other than adding new items to them using the array push() method. The accounts and tagged properties must contain account IDs (you can get these IDs from the Accounts page in Spotlight's Settings - they're called "Spotlight ID"). Hashtags are objects that specify a tag and a sort (either "popular" or "recent").

feed.options.accounts.push(68);
feed.options.hashtags.push({tag: "surfing", sort: "popular"});

More information

If you're a PRO customer and require more information and/or assistance using the JS API, contact our customer support and we'd be glad to help you out .