Custom CSS: classes and variables

Almost everything about how swatches look is a control on the Appearance page, and that is the right place to change it — those settings survive updates and apply per look and per surface.

This page is for the rest: the times you need something the controls do not offer. Swatchfy exposes 29 stable class names and 78 CSS custom properties for exactly that.

Put your rules in Swatchfy → Settings → Custom CSS. They are injected on the storefront after the app's own stylesheet.

⚠ Read this first: you will usually need !important

Swatchfy writes its variables inline on each swatch row, from Liquid at page render and again from JavaScript after the config loads. Inline styles beat stylesheet rules, so this does nothing:

/* Does not work — the inline value wins */
.swatchfy-swatches { --kx-bc: #000; }

and this works:

.swatchfy-swatches { --kx-bc: #000 !important; }

Rules that target ordinary properties rather than the variables behave normally and need no !important:

.swatchfy-swatch-item { box-shadow: 0 1px 3px rgba(0,0,0,.15); }

Prefer that second form when you can. Overriding a variable fights the app's own settings; adding a property the app does not set does not.

The classes

Row structure

Product page and product cards are two namespaces

Everything in this section is the product page. Card swatches render under their own names, so a rule written for one does not reach the other:

The state and look modifiers below — --pill, .swatchfy-selected, .swatchfy-soldout and the rest — are shared.

One swatch

Which look is rendering

.swatchfy-swatch--bare · --framed · --frameddot · --pill · --swatchpill · --priced · --more

--more is the "+3" counter when an option has more values than fit.

State

Overflow

.swatchfy-swatches--slides · .swatchfy-swatches__slider · .swatchfy-swatches__arrow appear when the row is set to carousel.

The variables

The names are terse but systematic. Read them as group + property, and two suffixes mean state: h = hover, s = selected.

So --kx-plbcs is pill · border colour · selected, and --kx-bgh is background · hover.

To read the exact current value for any of them, inspect a swatch row in your browser's dev tools — every variable in play is printed on the row element.

Recipes

A thicker ring on the selected swatch

.swatchfy-swatches { --kx-bws: 3px !important; --kx-bcs: #111 !important; }

Square swatches on collection cards only

.swatchfy-card-swatches .swatchfy-card-swatch { border-radius: 2px; }

Dim sold-out values further than the setting allows

.swatchfy-swatch-item.swatchfy-soldout { opacity: .35; }

Style one option only — use the row's own data attribute rather than a class, and prefer the index, which survives translation:

.swatchfy-swatches[data-swatchfy-option-index="0"] .swatchfy-swatch-item {  
border-radius: 50%;
}

Stability

The class names and data attributes above are treated as public and are kept stable across updates.

The --kx-* variables are also stable, but their values move whenever a merchant changes a setting on the Appearance page — that is what they are for. If a rule must hold regardless of the settings, target the property directly rather than the variable.