Back to docs

Embedded widget

The Behold Instagram widget is easy to use, highly configurable and works on all 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:

<behold-widget feed-id="L7mnQCHvZeMZLbNXmJll"></behold-widget>
<script>
  if ('noModule' in HTMLScriptElement.prototype) {
    const d=document,s=d.createElement('script');s.type='module';
    s.src='https://w.behold.so/widget.js';d.body.appendChild(s);
  }
</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 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

Settings: Filter

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.

Settings: Layout

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.

Post aspect ratio

This sets the aspect ratio of posts in your widget. There are a number of predefined values, or your can set your own.

Settings: Appearance

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:

  • Vibrant
  • Vibrant light
  • Vibrant dark
  • Muted
  • Muted light
  • Muted dark
  • Dominant

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.

Settings: Hover

Hover contents

Determines what content is shown on hover.

  • Icon: Show an icon representing the post type (image, video, gallery)
  • Caption: Show the post caption
  • None: Show nothing

Hover effect

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

  • Fade: Applies a semi-transparent black overlay to darken the image
  • Zoom Fade (default): Combined zoom and fade
  • Blur: Blurs the image
  • Zoom Blur: Combined zoom and a blur
  • To Greyscale: De-saturates the image so it renders in greyscale
  • Zoom to Greyscale: Combined zoom and greyscale
  • From Greyscale: All images will appear in greyscale. When you hover over a post, it will be showin in full-color
  • Zoom from Greyscale: Combined zoom and from-greyscale effects
  • None: No hover effect is applied

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.

  • Default: Black with 35% opacity
  • Auto: An auto-extracted color from the image, using the Dominant algorithm.
  • Custom color: Set your own overlay color

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.

Settings: Video

Autoplay videos

When turned on, video posts will autoplay muted as soon as they load.

Play videos on hover

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

Settings: Behavior

On click

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

  • Link to post: Navigate to the original post in Instagram
  • Link to profile: Navigate to the user profile page in Instagram
  • Custom link: Navigate to a custom link, set in the Custom link URL field
  • Open popup gallery: Opens a popup carousel of your widget’s posts
  • Do nothing: No click behavior

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

Controls whether your linked posts open in a new tab

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

  • Auto: styles the popup with a light or dark theme based on user operating system settings
  • Light: force light theme
  • Dark: force dark theme

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.

  • To start, navigate to the Breakpoints panel, click Add breakpoint and enter a pixel width. At or below this width, your breakpoint-specific styles will apply.
  • You can set number of posts, number of columns, column gap, row gap, and rounded corners for each breakpoint. The number of posts displayed at a given breakpoint cannot exceed the primary max. posts setting.
  • To test your breakpoints, you can adjust the width of the preview area. Simply click and drag one of the handles to either side of the widget. The current width of the preview area is displayed at the top of the screen.
  • In image #2 below you can see that the preview area width has been reduced to 590 pixels, and thus the < 600 breakpoint is being applied: 4 posts, 2 columns, no rounded corners, and no column or row gaps.
  • In image #3 the preview area has been shrunk further to 360 pixels, and thus the < 400 breakpoint is being applied: 1 post, 100% rounded corners.

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!

For instructions on adding Behold to specific platforms, you can refer to our integration guides.

Ready to give it a try?

Sign up for free