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

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:

• 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.

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.

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.

• 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

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".

• 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!

• Using Behold with WordPress
• Using Behold with Webflow
• 🚧 More guides on the way soon!

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)
})