The widget editor
Find your way around the widget editor: its tabs, the top bar, the live preview, and how saving works.
Where to find it: click Widgets, then Add widget, or click a widget's name or Edit button.
From the Widgets page, the editor opens full screen over the list. Your browser's Back button closes it, and the list refreshes when it does. If you open a widget from a direct link or reload the page, it opens as a normal admin page instead. It works the same way, and Save sits in the page header.
A new widget opens on the Media tab, where you give it a name and pick its clips.
The tabs
| Tab | What you set there |
|---|---|
| Media | The widget's name, layout, and placement (in the Basics card), and the clips it plays (in the Clips card). See Choose clips and Placement. |
| Stories / Carousel / Grid / Pop up / Product page | The tab is named after your layout. It covers size, shape, ring, background, and what shows on the thumbnails, plus options only that layout has. For Pop up, it covers when the pop up appears and how it looks. See Design. |
| Columns | Grid only. The tile pattern, and how many tiles fit per row on desktop, tablet, and mobile. See Grid columns and pattern. |
| Player | What happens when a shopper taps a clip: the fullscreen viewer, a mini player, or, on Carousel and Grid, playing inside the card. See Player. |
| Heading and clips | A line of text above the widget, the order clips play in, and the minimum number of clips. Pop up widgets show Clips here instead. See Heading and clip order. |
| Colors | The play badge on video thumbnails. See Colors. |
| A/B test | Test two versions of the widget against each other. See A/B testing. |
You can switch between tabs freely. Nothing is lost, and everything is saved together when you click Save.
Find a setting
Not sure which tab a setting is on? Use this table. Each card on a tab has its own title.
| Tab and card | Settings | More |
|---|---|---|
| Media → Basics | Widget name, Layout, Placement, Handle | Layouts, Placement |
| Media → Clips | Choose clips, the up and down arrows, the ✕ button | Choose clips |
| Layout tab → Size and spacing | Circle size, Card width, or Strip width, Size on mobile, Stretch to fill the row, Gap between…, Space above the widget, Space below the widget, Alignment, Alignment on mobile | Size and spacing |
| Layout tab → Shape | Clip shape, Corners | Shape, ring, and background |
| Layout tab → Ring | Thickness, Style, Fades from, Fades to, Ring color | Shape, ring, and background |
| Layout tab → Background | Use the page background, Background color | Shape, ring, and background |
| Layout tab → On the thumbnails | Preview videos, Product card, Card style, Card background, Card text | On the thumbnails |
| Carousel tab → Arrows and movement | Arrow position, Arrow style, Arrow button color, Arrow color, Advance every, Start over at the end | Carousel arrows and movement |
| Product page tab → What the strip shows and Movement | Clips on screen, Which clips, Show every clip when none match, Advance every, Start over at the end | The Product page layout |
| Pop up tab | Wait, After it is closed, Shape, Size, Corners | The Pop up layout |
| Columns | Tile pattern, Desktop, Tablet, Mobile | Grid columns and pattern |
| Player | Open in, Corner, Mini player size, Start with sound off, Show captions, Show a share button | Player |
| Heading and clips | Heading text, Alignment, Alignment on mobile, Text size, Gap below the heading, Text color, Play in this order, Show only with at least | Heading and clip order |
| Colors | Icon, Behind the icon, plus two add-to-cart colours that don't reach your storefront | Colors |
| A/B test | Variant B, the traffic split, and the test switch | A/B testing |
The top bar
| Item | What it does | Shown |
|---|---|---|
| Variant A / Variant B | Switch which version of the widget you're editing. | Once you've created a variant B |
| Embed code | Copies a Liquid snippet you can paste into your theme's code. You'll see Snippet copied. See Embed code. | Saved widgets |
| Add to theme | Opens your theme editor with a new UGC widget block. It opens the page type that matches Placement: the home page for Global / any page and Home page, or the product, collection, or page template. See Add the widget to your theme. | Saved widgets |
| Delete (bin) | Deletes the widget. | Saved widgets |
| Save | Saves your changes. | Always |
| Status badge | Draft until the first save. After that, Active if the widget has clips, or Needs media if it has none. | Always |
Save from Variant A
If your widget has a variant B, click Variant A before you click Save. Saving while Variant B is selected resets Placement to Global / any page. See A/B testing.
Active doesn't mean live
Active only means the widget has clips. Shoppers see it once it's saved and placed in your theme, on a page type its placement allows, with at least the minimum number of clips that aren't Draft in your library.
The preview
The right side of the editor shows a live preview that updates as you change settings, before you save. Underneath is a summary like 3 of 24 media · Carousel · Product pages.
The preview is a sketch of your widget, not your real storefront:
- It shows desktop sizes only. Mobile sizes, mobile alignment, and tablet and mobile columns aren't previewed.
- Thumbnails are still images. Preview videos, the player, and the add-to-cart button aren't shown.
- The product chip is a sample, Tagged product · $29.00, drawn on the first card of a Carousel or Grid whenever product cards are on.
- Captions show the clip's library name. Your storefront shows the file's alt text instead.
- Your Settings page, clip order, placement, and minimum number of clips aren't applied.
- Clips that are Draft in your library still show in the preview. Shoppers don't see them.
- A Product page preview shows every clip you picked, not just the ones matching a product, beside a greyed-out product column.
- A Bubble pop up can look like a rounded square in the preview. On your storefront it's always a circle.
- Carousel, Grid, Pop up, and Product page are drawn smaller than real size. Stories are drawn at real size.
To see the real thing, save and check your storefront.
Saving
Change what you need on any tab. A save bar appears.
Click Save in the save bar, or the Save button in the top bar.
Wait for Widget saved.
There's no separate publish step. Saving makes your changes live everywhere the widget is placed, from the next time a shopper loads the page.
If a save fails, a Could not save banner explains why:
| Message | What to do |
|---|---|
| Name is required. | Fill in Widget name on the Media tab. |
| Pick at least one video or image from Shopify Files. | Add at least one clip. See Choose clips. |
| Variant B needs at least one clip. | Open variant B and add a clip, or delete variant B. |
| Some files are still processing. Wait a moment, then save again. | A clip's file isn't ready yet, so wait and save again. If it keeps happening, the file may have been deleted from Shopify Files. Remove that clip from the widget. |
| This widget is too large. Remove some clips and save again. | Remove a few clips. |
| Could not save this widget: followed by a reason | Shopify refused the save. Try again, and contact support if it keeps happening. |
Numbers outside a setting's range are adjusted to the nearest allowed value when you save.
Undo your changes
Click Discard in the save bar.
Confirm. Everything goes back to the last saved version.
Rename a widget
Open the widget and go to the Media tab.
Change Widget name in the Basics card.
Click Save.
Theme blocks and embed code keep working. The theme editor lists the widget under its new name.
The Handle under Basics is the widget's permanent ID. It never changes. Copy it with the copy button if support asks for it.
Delete a widget
Click the Delete (bin) button in the top bar.
Click Delete widget to confirm.
It works the same as deleting from the Widgets page: it's permanent, it removes the widget's analytics, and you should remove its block from your theme.