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.

Basic Implementation

<unify-stock-widget
  api-key="your-api-key"
  item-id="your-item-id"
  location-id="your-location-id"
  mode="mixed-basket"
>
  <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
`mode`	String	Yes	Display mode: `"stock-info"` (view only) or `"mixed-basket"` (with add-to-cart)
`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 (required for `mixed-basket` mode)

Events

`add-to-cart`

Fired when the form is submitted and valid (only in mixed-basket mode). 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:

{
  itemId: string,           // Item ID from the widget
  locationId: string,       // Location ID from the widget
  source: string            // 'location' (store stock) or 'unified' (central stock)
}

`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:

{
  itemId: string,           // Item ID from the widget
  locationId: string,       // Location ID from the widget
  source: string            // 'location' (store stock) or 'unified' (central stock)
}

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% (%qty% p. remaining)"`	Label for store stock option. Supports `%store_name%` and `%qty%` placeholders
`unifiedStockLabel`	`"Central and/or Unified Stock (%qty% p. remaining)"`	Label for unified stock option. Supports `%qty%` placeholder

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
`noStockInfoAvailable`	`"No stock information available."`	Message when no stock data available

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

Stock info only (read-only display)

<unify-stock-widget
  api-key="your-api-key"
  item-id="ITEM-12345"
  location-id="LOC-789"
  mode="stock-info"
></unify-stock-widget>

With add-to-cart functionality

<unify-stock-widget
  api-key="your-api-key"
  item-id="ITEM-12345"
  location-id="LOC-789"
  mode="mixed-basket"
>
  <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"
  mode="mixed-basket"
>
  <button slot="add-to-cart-btn" type="submit">Add to Cart</button>
</unify-stock-widget>