Unify Stock Widget

Display real-time stock availability from store locations and unified inventory. Allows customers to choose stock source and add items to cart.

For installation instructions, see Getting Started with Unify Widgets.

⚠️ Removed: mode attribute. The widget no longer has a mode attribute — it only ever renders the mixed-basket (with add-to-cart) form. Surfacing store stock, click & go, and delivery information as headless, placeable blocks is now the role of <unify-delivery-promises-widget>.

Basic Implementation

<unify-stock-widget
  api-key="your-api-key"
  item-id="your-item-id"
  location-id="your-location-id"
>
  <button slot="add-to-cart-btn" type="submit">Add to Cart</button>
</unify-stock-widget>

Component Attributes

Attribute	Type	Required	Description
`api-key`	String	Yes	API key for Unify requests
`item-id`	String	Yes	Product item identifier to check stock for
`location-id`	String	Yes	Store location identifier
`demo`	Boolean	No	Enable demo mode for testing

Component Properties

Property	Type	Required	Description
`config`	Object	No	Configuration object (see Config Options)

Slots

Name	Description
`add-to-cart-btn`	Custom button element for adding item to cart

Events

`add-to-cart`

Fired when the form is submitted and valid. Use this event to handle the cart addition.

widget.addEventListener('add-to-cart', (event) => {
  const { item: { id, reference }, locationId, source } = event.detail;
  console.log(`Add ${id} from ${source} to cart`);
});

Detail shape:

{
  item: {
    id: string,             // Item ID from the widget
    reference: string       // Item reference from the widget
  },
  locationId: string,       // Location ID from the widget
  source: string             // 'location' (store stock), 'unified' (central stock) or 'warehouse' (see note below)
}

`stock-source-change`

Fired when the user changes the stock source (store or central).

widget.addEventListener('stock-source-change', (event) => {
  const { item: { id, reference }, locationId, source } = event.detail;
  console.log(`Stock source changed for ${id} to ${source}`);
});

Detail shape:

{
  item: {
    id: string,             // Item ID from the widget
    reference: string       // Item reference from the widget
  },
  locationId: string,       // Location ID from the widget
  source: string             // 'location' (store stock), 'unified' (central stock) or 'warehouse' (see note below)
}

Warehouse mode. Some locations deliver only from a specific warehouse instead of the unified stock pool (e.g. a StoreApp configured to ship from warehouse stock only). When the /widgets/stock-mixed-basket API returns a stock_warehouse field instead of stock_unified, the widget automatically switches its second stock option to warehouse mode: it uses the warehouseStockLabel/warehouseStockName/warehouseOutOfStockMessage config options (see below) and emits source: 'warehouse' instead of source: 'unified'. This is entirely driven by the API response — no widget attribute or config toggles it.

Config Options

Customize widget text and behavior through the config property.

document.querySelector('unify-stock-widget').config = {
  storeStockLabel: 'Store Stock %store_name% (%qty% left)',
  unifiedStockLabel: 'Central Stock (%qty% left)',
  loadingMessage: 'Loading stock...'
};

Stock Labels

Option	Default	Description
`storeStockLabel`	`"Store Stock %store_name% - %state% (%qty% p. remaining)"`	Label for store stock option. Supports `%store_name%`, `%state%` and `%qty%` placeholders
`storeStockName`	`"Store Stock"`	Fallback store name used in `storeStockLabel` when no location name is available
`unifiedStockLabel`	`"Unified Stock - %state% (%qty% p. remaining)"`	Label for unified stock option. Supports `%state%` and `%qty%` placeholders
`unifiedStockName`	`"Unified Stock"`	Display name for the unified stock option
`warehouseStockLabel`	`"Warehouse Stock - %state% (%qty% p. remaining)"`	Label for the warehouse stock option, used instead of `unifiedStockLabel` in warehouse mode. Supports `%state%` and `%qty%` placeholders
`warehouseStockName`	`"Warehouse Stock"`	Display name for the warehouse stock option
`inStockLabel`	`"In Stock"`	`%state%` placeholder value when the selected source has available quantity
`outOfStockLabel`	`"Out of Stock"`	`%state%` placeholder value when the selected source has no available quantity

Status Messages

Option	Default	Description
`loadingMessage`	`"Loading stock information..."`	Text shown while fetching stock data
`errorMessage`	`"Error loading stock information. Please try again later."`	Error message on load failure
`missingParamsMessage`	`"Missing item ID or location ID."`	Error message shown when `item-id` or `location-id` is missing
`noStockInfoAvailable`	`"No stock information available."`	Message when no stock data available
`locationOutOfStockMessage`	`"Selected store stock is not available"`	Validation error shown when submitting with the store source selected but out of stock
`unifiedOutOfStockMessage`	`"Selected unified stock is not available"`	Validation error shown when submitting with the unified source selected but out of stock
`warehouseOutOfStockMessage`	`"Selected warehouse stock is not available"`	Validation error shown when submitting with the warehouse source selected (warehouse mode) but out of stock

Styling

CSS Custom Properties (recommended)

All visual tokens (colors, sizes, spacing, fonts) are exposed as CSS custom properties prefixed with --unify-. This is the stable styling API.

Set them on the widget element or any ancestor:

unify-stock-widget {
  --unify-stock-widget-gap: 1.5em;
  --unify-stock-error-color: #b91c1c;
}

To discover all available properties:

Open browser DevTools
Inspect the <unify-stock-widget> element
Look at the Computed tab for all --unify-* entries
Edit them live in the Styles panel to preview

CSS Parts

Structural elements can be targeted using ::part():

unify-stock-widget::part(location-label--disabled) {
  opacity: 0.3;
}

⚠️ Parts may change between versions. Use CSS custom properties where possible.

To find available parts, inspect the widget's shadow DOM in DevTools — every element with a part attribute is targetable from outside.

Examples

With add-to-cart functionality

<unify-stock-widget
  api-key="your-api-key"
  item-id="ITEM-12345"
  location-id="LOC-789"
>
  <button slot="add-to-cart-btn" type="submit">Add to Cart</button>
</unify-stock-widget>

<script>
  const widget = document.querySelector('unify-stock-widget');
  
  widget.config = {
    storeStockLabel: 'In-Store (%store_name%)',
    unifiedStockLabel: 'Available Online'
  };
  
  widget.addEventListener('add-to-cart', (event) => {
    const source = event.detail.source === 'location' ? 'store' : 'central';
    console.log(`Added to cart from ${source}`);
    // Update your cart/basket UI
  });
</script>

Styled with custom theme

<style>
  unify-stock-widget {
    --unify-stock-widget-gap: 2em;
    --unify-stock-error-color: #dc2626;
  }
  
  unify-stock-widget::part(location-label--disabled) {
    opacity: 0.5;
    cursor: not-allowed;
  }
</style>

<unify-stock-widget
  api-key="your-api-key"
  item-id="ITEM-12345"
  location-id="LOC-789"
>
  <button slot="add-to-cart-btn" type="submit">Add to Cart</button>
</unify-stock-widget>