Navigation Back to home

BuyBox

A commerce buy box for product variants, quantity changes, pricing updates and add-to-cart actions.

Import
the javascript logo
import { BuyBox } from "@schukai/monster/source/components/form/buy-box.mjs";
Source
the git logo
Package
the npm logo
Since
4.65.0

Introduction

The Monster BuyBox is the commerce-oriented control for product purchase flows. Use it when a product page needs variant selection, quantity handling, pricing feedback and a direct add-to-cart or order action.

When to use BuyBox

  • Use it for sellable products: It combines the typical inputs that belong to a purchase decision.
  • Use it when variants affect availability or price: The component can react to valid combinations.
  • Do not use it for generic forms: Outside commerce flows, a custom field set is usually the better fit.

Typical mistakes

Keep the product contract explicit. If variant, price and stock state come from different sources without one clear mapping, the buy box quickly becomes hard to reason about for users and for implementers.

Basic Buy Box

A basic buy box with static product data, variants, and tier pricing. It uses slots for title and info and configures the control entirely through options.

Classic Tee

Soft cotton, regular fit.

Ships in 2-3 days.

Javascript

import '@schukai/monster/source/components/form/buy-box.mjs';

const box = document.getElementById('buy-box-basic');

box.setOption('product', {
    sku: 'TSHIRT-001',
    name: 'Classic Tee',
    currency: 'EUR',
    taxIncluded: true,
    taxRate: 19,
    delivery: '2-3 days',
    stock: 12,
    unitLabel: 'pcs'
});

box.setOption('pricing', {
    price: 29.9,
    listPrice: 39.9,
    basePrice: 29.9,
    basePriceUnit: '1 pcs',
    tiers: [
        { min: 1, price: 29.9 },
        { min: 5, price: 27.9 },
        { min: 10, price: 24.9 }
    ]
});

box.setOption('variants', {
    dimensions: [
        { key: 'color', label: 'Color' },
        { key: 'size', label: 'Size' }
    ],
    data: [
        { id: 'TS-RED-S', color: 'Red', size: 'S' },
        { id: 'TS-RED-M', color: 'Red', size: 'M' },
        { id: 'TS-BLU-M', color: 'Blue', size: 'M' }
    ]
});

box.setOption('quantity', {
    min: 1,
    max: 20,
    step: 1
});<script type="module">import '@schukai/monster/source/components/form/buy-box.mjs';

const box = document.getElementById('buy-box-basic');

box.setOption('product', {
    sku: 'TSHIRT-001',
    name: 'Classic Tee',
    currency: 'EUR',
    taxIncluded: true,
    taxRate: 19,
    delivery: '2-3 days',
    stock: 12,
    unitLabel: 'pcs'
});

box.setOption('pricing', {
    price: 29.9,
    listPrice: 39.9,
    basePrice: 29.9,
    basePriceUnit: '1 pcs',
    tiers: [
        { min: 1, price: 29.9 },
        { min: 5, price: 27.9 },
        { min: 10, price: 24.9 }
    ]
});

box.setOption('variants', {
    dimensions: [
        { key: 'color', label: 'Color' },
        { key: 'size', label: 'Size' }
    ],
    data: [
        { id: 'TS-RED-S', color: 'Red', size: 'S' },
        { id: 'TS-RED-M', color: 'Red', size: 'M' },
        { id: 'TS-BLU-M', color: 'Blue', size: 'M' }
    ]
});

box.setOption('quantity', {
    min: 1,
    max: 20,
    step: 1
});</script>

HTML

<monster-buy-box id="buy-box-basic">
    <span slot="title">Classic Tee</span>
    <p slot="info">Soft cotton, regular fit.</p>
    <p slot="shipping">Ships in 2-3 days.</p>
</monster-buy-box>

Stylesheet

/** no additional stylesheet is defined **/
Open in playground

Component Design

The monster-buy-box control uses Shadow DOM to keep its internal structure and styles isolated. Styling hooks are exposed via exported parts and slots.

Slots

  • title: Header area above the product configuration.
  • info: Optional description or marketing text.
  • shipping: Shipping or delivery notes.
  • footer: Additional content below the actions.

Exported Parts

Use ::part() to style key regions such as pricing, quantity, and actions:

  • header, body, slots
  • variants, variants-control
  • quantity, quantity-label, quantity-control, quantity-input
  • prices, price, list-price, sum, base-price, tax, total
  • actions, submit, submit-label

monster-buy-box::part(price) {
    font-size: 1.4rem;
    font-weight: 700;
}

monster-buy-box::part(submit) {
    min-width: 10rem;
}

HTML Structure

<monster-buy-box></monster-buy-box>

JavaScript Initialization

const element = document.createElement('monster-buy-box');
document.body.appendChild(element);

Exported

BuyBox

Derived from

CustomControl

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomControl.

Option
Type
Default
Description
templates
object
Template definitions
templates.main
string
undefined
Main template
labels
object
undefined
Labels
features
object
Feature toggles
features.messages
boolean
true
Show status messages
features.rowSelects
boolean
false
Allow row selects in variant select
features.combinedSelect
boolean
false
Allow combined variant select
features.allowDecimal
boolean
false
Allow decimal quantities
product
object
Static product config
pricing
object
Static pricing config
variants
object
undefined
Variant configuration (passed to monster-variant-select)
quantity
object
Quantity configuration
cart
object
Cart configuration (endpoint + mapping or cart control selector)
stock
object
Stock configuration (endpoint + mapping)
datasource
object
Datasource config (selector or rest)
mapping
object
Mapping from datasource data to product values
actions
object
Callback actions

  • since
  • deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomControl.

  • data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
  • data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomControl.

Behavioral methods

refresh()
Returns
  • {BuyBox}
Re-apply options and mapped data.

Static methods

[instanceSymbol]()
Returns
  • {symbol}
This method is called by the instanceof operator.
getCSSStyleSheet()
Returns
  • {CSSStyleSheet[]}
getTag()
Returns
  • {string}

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()
Returns
  • {BuyBox}

Events

The component emits the following events:

  • monster-buy-box-change
  • monster-buy-box-valid
  • monster-buy-box-invalid
  • monster-buy-box-submit
  • monster-buy-box-success
  • monster-buy-box-error
  • monster-buy-box-loaded

For more information on how to handle events, see the mdn documentation.

The current width of the area is too small to display the content correctly.