Web Components

Use these framework-agnostic custom elements to render Open Shop commerce UI on any site.

Available components

Cart Button Cart icon with a live item-count badge. Toggles the cart slideout.

Cart Slideout Slide-in cart panel with line items, quantity controls, and checkout.

Product Details Full product detail page with media, variants, and add-to-cart.

Product List Grid of products with optional collection filtering.

Referral Tracker Capture and persist referral codes from the URL.

Single Product Card Compact card for a single product on any page.

API conventions

• Attributes are listed in kebab-case exactly as used on each custom element.
• If a component has no configurable attributes, the attributes table states None.

The same components.js that registers these elements also installs the JavaScript API — window.OpenShop plus a set of data-os-* attributes — for reading customer and cart state from your own code or markup.

Styling

Open Shop web components do not use the Shadow DOM. Their internal markup is rendered into the regular light DOM of your page, which means:

• Your site’s stylesheets apply to them — utility classes flow through normally.
• You can override any internal style by writing CSS selectors that target the elements inside a component. No ::part(), no :host, no piercing tricks, and no !important required.
• The browser’s developer tools show the full component markup, so you can inspect any element and write a selector against it.

Overriding styles

Every style components.js injects sits inside a CSS cascade layer named os-components:

What the bundle injects

@layer os-components {
  /* every component style Open Shop adds to your page */
}

Cascade layers are resolved before specificity and before source order. Any unlayered rule beats any layered rule — however specific the layered one is, and whichever stylesheet the browser loaded last. Your site’s CSS is unlayered unless you deliberately put it in a layer of your own, so your rules win by default.

The one exception is !important, where layer order is inverted: an !important declaration inside a layer outranks anything unlayered, including your own !important. The bundle uses that deliberately for exactly one rule — the one that keeps data-os-show elements hidden. Everything else it injects is a normal declaration your CSS overrides freely.

That turns restyling back into ordinary CSS. A single class selector is enough, and you never need to know the generated hash classes on our elements:

Before — fighting the cascade

os-cart-slideout .os-cart-slideout .os-cart-item-name {
  color: red !important;
}

After — plain CSS

.os-cart-item-name {
  color: red;
}

Write selectors scoped to the custom element tag when you want an override to affect only Open Shop components:

site.css

/* Restyle the cart button */
os-cart-button button {
  background: #111;
  color: #fff;
  border-radius: 9999px;
}

/* Restyle product cards inside the product list */
os-product-list .product-card {
  border: 1px solid #e5e7eb;
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04);
}

What you can delete

If you wrote CSS against an older bundle, it keeps working exactly as it does today — !important in an unlayered rule still wins against every component style. The one thing it can no longer do is re-show an element the data-os-* layer hid, which is the exception described above. Nothing else regresses, so clean up at your own pace. When you do, these workarounds can all go:

• !important added only to out-rank a component style.
• Doubled or repeated selectors written to out-specify ours, like os-cart-slideout .os-cart-slideout .os-cart-item-name.
• Generated hash classes such as .svelte-1a2b3c pinned in your selectors.
• Load-order hedges — rules duplicated or re-declared because the component stylesheet arrives after yours.

The one exception is components.css. That file defines the five global --os-* token defaults on :root and is deliberately not layered, because it is meant to be overridden by redefining the variables — see Theming with CSS variables. Nothing changes there.

Browser support

Cascade layers need Chrome 99, Safari 15.4, or Firefox 97 — all released in early 2022. Older browsers ignore the whole layer block, which means they render the components unstyled rather than mis-styled.

Using Webflow?

All of your CSS counts as unlayered, wherever you write it: the site-wide custom code in Site settings, per-page custom code, and CSS inside an Embed block. Any of the three beats a component style, so put your overrides wherever suits you.

Theming with CSS variables

Most visual styling is exposed through --os-* CSS custom properties, so you can re-theme components without writing element selectors. Set them anywhere that cascades to the component — :root, a wrapper element, or the custom element tag itself:

:root {
  --os-primary: #ff5a5f;
  --os-cart-btn-radius: 9999px;
}

Each component page lists its own variables. The global tokens below are inherited by every component, and most component-specific variables fall back to them — so overriding these five re-themes the whole UI at once:

CSS variable	Default
--os-foreground	#020617
--os-muted-foreground	#64748b
--os-primary	#5eb3e4
--os-primary-foreground	#fafafa
--os-border	#e2e8f0