Documentation
Embeddable widget

Embeddable widget

The Behold Instagram widget is easy to use, highly configurable and works on most modern platforms. Here we'll explain how to create your widget, customize it, and add it to a website.

How it works

Our embedded widget consists of a script tag that loads some lightweight JavaScript and a container for your feed. It looks like this:

<figure data-behold-id="L7mnQCHvZeMZLbNXmJll"></figure>
<script src="https://w.behold.so/widget.js" type="module"></script>

And here's the result:

Creating a widget

  1. First, connect an Instagram account
  2. Navigate to the feeds page and click on Add feed
  3. You will be prompted to choose between a user feed or hashtag feed. User feeds pull posts from a single account, hashtag feeds aggregate public hashtag content from across Instagram.
  4. Pick a source for your feed. If you are creating a hashtag feed, you must choose an advanced source.
  5. Select "Widget"
  6. Name your feed, or just click on Create feed to use the default name. You can change this later.
  7. You will be redirected to your widget admin page. Here you can see a preview of your widget, update settings, and access your embed code.

Widget types

We currently have two main widget types (with more on the way!):

Flexible grid

Our core widget. Highly configurable and responsive. This type of widget can be configured to suit almost any layout and design.

Gallery wall

Gallery wall widgets allow for beautiful and interesting layouts that break outside the standard grid. They cannot be adjusted by breakpoint, however, and are generally less configurable.

You can choose between multiple gallery wall layouts by going to Customize → Gallery wall design

Widget settings

Number of Posts

The maximum number of recent posts to fetch. Set this only as high as you need. Smaller = faster.

This number is limited by your plan. See the pricing page for details.

Allowed post types

This setting lets you choose which post types to include in your feed, from among images, videos , reels and albums.

Caption must include

Only posts that contain at least one of the text snippets you add here will be included in your feed. This is case-sensitive and can include spaces.

Caption may not include

Only posts that do not contain any of the text snippets you add here will be included in your feed. This is case-sensitive and can include spaces.

Hashtag feeds can take a few minutes to preload when combined with this setting.

Max. width

Sets a maximum pixel width for your feed. When this option is disabled your feed will always fit the width of its container.

Either way your feed will never grow wider than its containing element.

Alignment

Sets a maximum pixel width for your feed. When this option is disabled your feed will always fit the width of its container.

Either way your feed will never grow wider than its containing element.

# of columns

The number of columns your posts will be arranged into. Columns are automatically sized to fit the width of the widget.

Column gap

The space (in pixels) between columns of posts.

Row gap

The space (in pixels) between rows of posts.

Rounded corners

Applies a percentage-based rounding to the corners of your widget posts. If you set this to 100% your posts will be cropped into circles.

Placeholder colors

This sets the colors that show while your images are loading. These colors are extracted from the images themselves using one of 7 algorithms:

If you select Custom tone, a color picker will appear, and you can set the loading colors to a specific brand color. The colors will be tinted/shaded based on the underlying image.

If you select None, the images will be transparent before loading.

Placeholder custom tone

Only available if the Placeholder colors option is set to Custom tone. Allows you to pick a color to show while images are loading.

Hover contents

Determines what content is shown on hover.

Hover effect

Determines what, if any, animation to apply when a post is hovered-over.

Hover overlay color

Only available when the Hover effect option is set to Fade or Zoom fade or the Hover contents option is set to Caption. Sets the color of the overlay that darkens the image.

Hover overlay custom color

Only available when the Hover overlay color option is set to Custom color. Allows you to set the overlay to any color.

Hover overlay opacity

Only available when the Hover overlay color option is set to Auto or Custom color. Sets the overlay opacity.

Play videos on hover

When turned on, video posts will autoplay muted when they are hovered.

On click

Determines what happens when someone clicks on a post in your widget.

Custom link URL

Only available when the On click option is set to "Custom link". Sets the URL widget posts will link to.

Open links in a new tab

Controls whether your linked posts open in a new tab

Popup color theme

Only available when the On click option is set to "Open popup gallery".

Breakpoints

You can apply unique styling based on the width of your widget. This allows you to show different versions for users on desktops, laptops, tablets and mobile devices.

Domain whitelist

Your feed will only function on domains listed here, or on any domain if left blank. By default your feed will work on any domain.

Subdomains are independent and wildcards are not supported. So example.com and  www.example.com must be entered separately. The protocol (e.g. https://) is ignored.

localhost is always whitelisted.

Browser support

Our widget works on all modern browsers, including Firefox, Chrome, Microsoft Edge, Brave, Vivaldi, Opera and Safari.

Internet Explorer is not supported. IE only represents a small fraction of web traffic, and is officially no longer being supported by Microsoft as of June 2022.

Targeting modern browsers allows us to rapidly improve our widget and provide a fast, modern experience to your users without being bogged down by the requirements of legacy platform support.

Adding your widget to a website

The Behold widget works on any platform that lets you add or edit custom snippets of HTML. So every major site-builder, CMS and e-commerce platform should be covered.

Just paste your embed code wherever you can put HTML and you're good to go!

Reinitializing

If you're using one of our widgets in a dynamic environment like a single page app, you may find it helpful to reinitialize our widgets after the first page load.

To do this, simply call window.beholdWidgets.initialize() after widgets.js has loaded. This will load widgets in any containers with the data-behold-id property.

Events

Whenever a widget finishes loading, a behold:widget-loaded event is fired on the window object. The feed ID is contained in the detail property of the event.

window.addEventListener('behold:widget-loaded', (event) => {
   console.log(event.detail.id)
})

Ready to give it a try?

Sign up for free