Create your first widget
Pick a layout, choose your clips, and save a widget that's ready to add to your theme.
A widget is one arrangement of clips on your storefront, such as a row of story circles or a carousel of video cards. We'll build a simple one with the default settings.
Do this first
Widgets only use clips from your Video library. If it's empty, start with Add your first videos.
1. Start a new widget
Click Widgets in the app menu.
Click Add widget. The widget editor opens full screen on the Media tab, with a live preview on the right.
You can also start from Home: click Create widget in the Setup guide, or in the box that says Create your first widget. Both lead to the same editor.
2. Fill in the basics
Under Basics:
| Setting | What to do |
|---|---|
| Widget name | Type a name you'll recognise, such as Home page stories. Only you see it. It's how you'll find the widget in the theme editor. You can't save without one. |
| Layout | Leave it on Stories, or pick Carousel, Grid, Pop up, or Product page. See Layouts for what each one looks like. |
| Placement | Leave it on Global / any page. Where the widget appears is decided by where you place its block in your theme. See Placement. |
| Handle | Nothing to do. It's a code the app makes for you the moment you save, and the theme uses it to find the widget. The copy button next to it copies it. You only need it if you paste embed code yourself. |
Product page layout
Product page is built for product pages. From the clips you add to it, it shows the ones tagged with the product being viewed, and its placement is locked to Product pages. See The Product page layout.
3. Choose the clips
In the Clips card, click Choose clips. The Media library window opens, showing the clips in your Video library. If you have a lot, type in Search files to narrow them down.
Click the clips you want. Each one you pick shows Selected. Click a selected clip again to take it out. You can add up to 24.
Click Done. Your clips appear in the list and in the preview. The list's badge shows how many you've picked, for example 3 of 24.
If the window says Your library is empty, go back to Add your first videos. You can't upload from inside the widget editor.
Clips play from the top of the list down. To change the order, click the up or down arrow beside a clip. To take a clip out, click its ✕. Once you have clips, the button changes to Add more clips.
The list order isn't being followed?
If Heading and clips → Play in this order is set to Videos first, images after or Shuffle on every visit, a banner above the list says the storefront won't follow it. Set it back to Manual to use your order. See Choose clips.
4. Save
Click Save at the top right. You'll see Widget saved, and the badge next to the button changes from Draft to Active.
If you see Could not save, the message says why. The usual causes:
| Message | What to do |
|---|---|
| Name is required. | Type a Widget name. |
| Pick at least one video or image from Shopify Files. | Choose at least one clip. |
| Some files are still processing. Wait a moment, then save again. | A clip you picked is still being prepared by Shopify. Wait a minute and save again. |
Your widget is saved, but it isn't on your storefront yet. The next two pages cover that. Once it's saved, two buttons appear in the top bar for that: Add to theme and Embed code.
Want to change the look?
You can do it now or later. The tab named after your layout controls size, shape, ring, and what shows on the thumbnails. Player controls what happens when a shopper taps a clip, Heading and clips adds a line of text above the widget, and Colors sets the play badge and add-to-cart button colours. Grid widgets also have a Columns tab, and Pop up widgets have their own settings and a Clips tab in place of Heading and clips. The A/B test tab lets you try two versions. See Design and The widget editor.
Next
Turn on the app embed: the switch that lets your widgets show on your storefront.