Visual Settings Guide Rubik Variant Images & Swatch
Overview
The Swatch style editor lets you design your variant swatches without writing any code. Every change is drawn in the live preview beside the settings, and nothing reaches your storefront until you click Save.
Two surfaces, two sets of settings
The editor opens on two tabs, and each one keeps its own complete design:
- Product page: the swatches on the product page itself.
- Product card: the smaller swatches on collection and search cards. This tab only affects your store once product card swatches are enabled on the Swatch page; the editor shows a warning when they are not.
A handful of settings are shop-wide rather than per tab, and are noted as such below.
Presets and quick sizes
At the top of the page, above everything else, are one-click starting points. Applying a preset sets every visual setting at once, including the layout; you can then adjust anything you like. The presets differ per tab, because a 70px swatch that works on a product page is far too large on a collection card.
- Product page: Minimal, Rounded, Circle, Polaroid, Polaroid with price, Bold, Outlined, Carousel, Carousel circles.
- Product card: Minimal, Dots, Rounded, Bold, Carousel, Carousel dots.
Under the presets, XS to XL quick sizes scale every dimension together: swatch size, pill padding, pill font size, minimum width and spacing. They leave shape, color and effects alone, so you can pick a look with a preset and then set its scale independently.
Swatch image source
This is the first real decision, and it sits above the settings sections because it controls what each swatch shows rather than how it looks. Set separately for the product page and product cards.
| Option | What each swatch shows |
|---|---|
| Automatic (recommended) | Tries the custom swatch image, then the custom swatch color, then the variant image, in that order. Whichever exists first wins. |
| Custom swatch image | Forces the image you assigned to the option value. |
| Custom swatch color | Forces the color you assigned to the option value. |
| Variant image | Forces the photo attached to the variant itself. |
Two things are worth knowing. Custom image and custom color include anything you set in Bulk set swatches, the shop-wide swatch library: a library image counts as the custom image for any product that has none of its own. And forcing a source is not a hard filter: a value that does not have that source falls back to Automatic rather than disappearing. That is why forcing a source can look like it did nothing.
The preview says so out loud. Pick a product and it will tell you, for example, that 3 of 4 values have no custom color and fell back, and name them.
Swatch layout: grid or carousel
Next to the image source, and also set per tab.
| Layout | Behavior |
|---|---|
| Grid (default) | Swatches wrap onto a second line when they do not fit. This is how the app has always rendered. |
| Carousel | Swatches stay on one line that scrolls sideways. Nothing is hidden; the shopper scrolls to the rest. |
The carousel applies to image and color swatch rows only. A row of size pills stays a wrapping list, because a shopper comparing sizes wants to see them all at once.
Scrolling works by swiping on a phone, by trackpad, and with the keyboard (arrow keys move between swatches and the browser scrolls the focused one into view). On desktop, arrow buttons appear when the row is wider than the space it has. Each arrow hides itself once you reach its end of the row, and both stay hidden when everything already fits. Product card swatches deliberately get no arrows: a card is already a click target, and buttons floating over it would compete with it.
Choosing the carousel turns off the layout limit below, since a scrolling row already shows every swatch.
Image and color swatches
Swatches that show a picture or a color.
Shape
| Shape | Corner radius | Notes |
|---|---|---|
| Square | 0 | The only shape that supports text labels under the swatch. |
| Rounded | 8px | Softer corners. |
| Circle | 50% | Works best with square images and the Cover image fit. |
Size and height
Size sets the width, and by default the height too, so swatches are square. Range 20px to 200px, default 70px on the product page and 30px on cards.
Height (optional) makes them rectangular. Useful when your product photos are landscape or portrait and you want the swatch to match. Click Reset to go back to square.
Image fit
- Contain (default): the whole image is visible, scaled to fit. May leave space around it.
- Cover: the image fills the swatch, cropping the edges. Best for circles.
Borders
Border width (default) and (selected) range from 0 to 5px. Their colors are set with
the color pickers beside them: light grey (#e5e5e5) unselected and dark grey (#333333)
selected by default. The selected border is the main signal telling a shopper which variant is active, so keep it
clearly different from the unselected one.
Image background color
Shown behind the image. Only visible with Contain fit when the image does not fill the swatch, or with transparent PNGs. Default white.
Hover zoom
Scales the swatch slightly when the shopper hovers it. 100% means no zoom.
Sold out image opacity
Set in the Sold out options section, this dims image swatches for unavailable variants. It defaults to fully opaque, so sold-out image swatches are marked by the diagonal line alone unless you change it.
Pill swatches
Text buttons for options without images, like Size or Material.
Shape and size
- Shape: Square, Rounded (8px) or Full rounded (capsule).
- Padding: vertical and horizontal, on one row of two sliders.
- Font size: 10px to 32px.
- Minimum width: keeps short labels like S, M and L the same width.
Colors
Pills have a full set for both states: background, text color and border color when unselected, and the same three when selected. The default selected pill inverts, dark background with light text, so the choice is unmistakable.
Sold out pill opacity
In the Sold out options section. Dims unavailable pills; default 0.9.
Show as dropdowns
Turns non-visual options into a native <select> instead of a row of pills. Useful for options with
many values, like a size run of twenty. This setting is shop-wide, not per tab. When it is on, a
Dropdown appearance group appears with its own background, text color, border color, border width, corner radius and
font size.
On phones the dropdown font size never goes below 16px, because iOS Safari zooms the page when a shopper focuses a smaller field.
Text labels
The variant name printed under each image or color swatch. Only available when the swatch shape is Square.
Style
- Compact: fixed height, long names are truncated with an ellipsis.
- Full text: the label grows to show the whole name.
All labels in a row are the same height, so a name that wraps to two lines does not leave its neighbours short.
Typography and spacing
- Font size: 8px to 20px.
- Bold text: off by default, in which case the label inherits your theme's weight.
- Text alignment: left, center or right.
- Padding: vertical and horizontal.
- Colors: text, background and border.
The swatch and the name under it are one card: a single border runs around the pair with no line between them, and selecting a swatch moves that border to your selected color. There is nothing to switch on for this.
Prices
The price of each color, printed under its name. Product page only, and like text labels it needs the swatch shape to be Square.
A color usually covers several variants, so the figure shown is the cheapest of them. When they are
not all the same price, a + is added, so $59.00+ reads as "from $59.00". You can turn
that marker off if you would rather show the number on its own. Prices are printed in your store's currency and
follow your money format.
- Font size: 8px to 20px.
- Padding: the space above and below the price.
- Bold and Text color.
The price sits inside the same card as the swatch and its name. The card has no lines inside it at all, only the border around the outside. If one of your colors has no price to show, the card simply ends after the name.
The Polaroid with price preset is this look ready made: a large square swatch, a bold caption and the price underneath.
Tooltips
A small bubble with the variant name, shown when a shopper hovers an image or color swatch. Hover does not exist on touch devices, so tooltips are a desktop affordance.
- Background color and background opacity.
- Text color, font size and corner radius.
While this section is open, the preview pins the selected swatch's tooltip visible so you can see your changes without chasing it with the mouse.
Hover and selection effects
Shadow on hover
Lifts the swatch under the cursor with a soft shadow. Applies to both image and pill swatches.
Ring around the selected swatch
An outline drawn outside the border, which reads as a much stronger selection signal than a thicker border. Enable it independently for image and color swatches and for pill swatches, then set its width, distance from the swatch, and color.
Option label settings
The "Color: Black" line above each row.
- Hide name, Hide value, Hide colon: hide the parts individually.
- Hide the whole label: no text above the swatches at all. The default on product cards.
- Font size and color.
- Use a different color for the value: gives the selected value its own color, so "Color:" can be grey while "Black" is dark.
Swatch margins
- Alignment: left, center or right. Also aligns the option label above. In carousel layout the row always starts at the left edge, since a scrolling row has to.
- Top and bottom margin: space above and below the whole block, 0 to 30px.
- Margin between options: space between one option group and the next, 0 to 50px.
- Margin between swatches: the gap between individual swatches in a row.
Sold out options
When a variant is unavailable the swatch gets a diagonal line through it. You can turn the line off, recolor it separately for image and pill swatches, and dim either type with its own opacity setting.
Layout limit and color split
Limit to one row
Shows only the swatches that fit on a single line and collapses the rest behind a +N button the shopper can click to reveal them. The fit is measured in the shopper's browser, so it adapts to their screen.
Max visible
A fixed cap instead: show at most N swatches, rest behind the same +N button. Ignored while Limit to one row is on.
Both limits stand down when fewer than two swatches would be hidden, since collapsing a single swatch behind a "+1" gains nothing. Both are also unused in the carousel layout.
Color split direction
How a swatch with two assigned colors divides between them: diagonal right, diagonal left, vertical or horizontal. This setting is shop-wide, not per tab.
Carousel arrows
This section only appears when the layout is set to Carousel. It styles the desktop scroll buttons: size, roundness (50% is a circle, 0% a square), background, arrow color and border color.
Custom CSS
For anything the settings do not cover. Your CSS is applied after everything above, so it can override any value. See the Custom CSS Reference for the full list of variables and class selectors. The field has a 4000 character limit.
The live preview
The preview sits beside the settings on desktop and follows you down the page as you scroll. On a phone it sits above the settings and scrolls normally.
Preview a real product
Click Preview a product and pick one from your catalog. The preview then renders that product's real options and real swatches, resolved exactly the way your storefront resolves them, including the swatch library and your forced image source.
It also tells you when your storefront would show something different from what you expect:
- If none of the product's options is in your Variant options list, the preview goes empty and says so. That is not a bug: the app only renders its picker when at least one option is a swatch option, and that product keeps your theme's own variant picker.
- If a product has only one variant, the app never shows swatches for it, and the preview says that too.
- If a forced image source found nothing for some values, the preview counts them and names a few.
The background swatches and image ratio under the preview only change the preview. They are never saved.
Restore defaults
Restore defaults in the top right resets every setting on the current tab, including custom CSS. Nothing is written until you click Save, so you can undo it with Discard.
Tips
- Start from a preset: pick the closest look, then adjust. It is faster than moving twenty sliders from the default.
- Circle swatches want Cover: with Contain, a non-square image leaves empty corners inside the circle.
- Match your theme: use your theme's own button or input border color for the unselected border, so the swatches look native.
- Check the selected state contrast: the selected border or ring must be clearly visible against your page background.
- Carousel for long colorways: if a product has fifteen or more colors, a carousel keeps the price and Add to cart above the fold.
- Preview a real product before you save: sample swatches cannot show you a missing custom color, and a real product can.
Related guides
- Custom CSS reference: go beyond visual settings with 100+ CSS variables
- Swatch click event: listen for swatch interactions with JavaScript
- Supported themes: full list of compatible Shopify themes