Skip to main content
The Widget Library (@protonagency/commerce-blocks-widget) provides pre-built Preact components for common commerce use cases. Built on top of the SDK, these widgets handle UI rendering, loading states, and user interactions out of the box.

​
Installation

npm install @protonagency/commerce-blocks-widget

​
Quick Start

import { initializeWidgets, registerAllWidgets } from '@protonagency/commerce-blocks-widget';
import '@protonagency/commerce-blocks-widget/styles';

initializeWidgets({
  layers: { accessToken: '...' },
  storefront: { shop: '...', accessToken: '...' },
  attributes: {
    optionSources: [
      { attribute: 'options.color', type: 'color' }, 
      { attribute: 'options.size' }
    ],
  },
});

registerAllWidgets();

​
Available Widgets

The library provides five main widgets as web components:
WidgetDescriptionKey Attributes
<browse-widget>Collection browsing with paginationdata-collection, data-sort, data-limit
<search-widget>Semantic search resultsdata-query, data-limit
<similar-widget>Similar productsdata-product-id, data-limit
<predictive-widget>Autocomplete suggestionsdata-query, data-limit
<image-search-widget>Image-based product searchdata-limit

​
Browse Widget

Display products from a merchandised collection with sorting and pagination: 
<browse-widget
  data-collection="summer-shoes"
  data-sort="best_selling"
  data-limit="24"
></browse-widget>

​
Attributes

​
data-collection
string
required
The collection handle to browse.
​
data-sort
string
required
The sort order code to apply.
​
data-limit
number
default:"24"
Number of products to display.

​
Search Widget

Display semantic search results: 
<search-widget 
  data-query="blue dress" 
  data-limit="24"
></search-widget>

​
Attributes

​
data-query
string
required
The search query string.
​
data-limit
number
default:"24"
Number of products to display.

​
Similar Products Widget

Display products similar to a reference product: 
<similar-widget 
  data-product-id="123456" 
  data-limit="8"
></similar-widget>

​
Attributes

​
data-product-id
string
required
The product ID to find similar products for.
​
data-limit
number
default:"8"
Number of similar products to display.

​
Predictive Search Widget

Display autocomplete suggestions: 
<predictive-widget 
  data-query="sho" 
  data-limit="5"
></predictive-widget>

​
Attributes

​
data-query
string
required
The partial search query for suggestions.
​
data-limit
number
default:"5"
Number of suggestions to display.

​
Image Search Widget

Allow users to search by uploading an image: 
<image-search-widget 
  data-limit="24"
></image-search-widget>

​
Attributes

​
data-limit
number
default:"24"
Number of products to display in results.

​
Tree-Shakeable Imports

Import only the widgets you need for smaller bundles: 
// Individual widgets
import { BrowseWidget } from '@protonagency/commerce-blocks-widget/browse';
import { SearchWidget } from '@protonagency/commerce-blocks-widget/search';

// Shared components only
import { ProductCard, Grid } from '@protonagency/commerce-blocks-widget/components';

​
Shared Components

The widget library exports shared components that you can use to build custom UIs:

​
ProductCard

A reusable product card component: 
import { ProductCard } from '@protonagency/commerce-blocks-widget/components';

<ProductCard 
  product={product}
  onClick={(product) => console.log('Clicked:', product.title)}
/>

​
Grid

A responsive grid layout for product cards: 
import { Grid } from '@protonagency/commerce-blocks-widget/components';

<Grid columns={4} gap="1rem">
  {products.map(product => (
    <ProductCard key={product.id} product={product} />
  ))}
</Grid>

​
Styling

Import the default styles or customize with CSS custom properties: 
// Import default styles
import '@protonagency/commerce-blocks-widget/styles';

​
CSS Custom Properties

Override the default styles using CSS custom properties: 
:root {
  --widget-primary-color: #ff4500;
  --widget-font-family: 'Helvetica', sans-serif;
  --widget-border-radius: 8px;
  --widget-spacing: 1rem;
}

​
Dependencies

The widget library has the following dependencies:
  • @protonagency/commerce-blocks-sdk - Core SDK (dependency)
  • preact - UI framework (peer dependency)
  • @preact/signals - Reactive state (peer dependency)