BuyBox

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

Import

import { BuyBox } from "@schukai/monster/source/components/form/buy-box.mjs";

Source

View source code

Package

@schukai/monster

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

Inventory Updates

Updates stock and quantity constraints through the BuyBox option contract.

Team license

Javascript

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

const box = document.getElementById("stock-buy-box");
box.setOption("product", {sku: "TEAM-10", name: "Team license", currency: "EUR", stock: 25});
box.setOption("pricing", {price: 199, listPrice: 249});
box.setOption("quantity", {min: 1, max: 25, step: 1});

document.getElementById("stock-buy-box-update").addEventListener("click", () => {
  box.setOption("product.stock", 3);
  box.setOption("quantity.max", 3);
});

HTML

<section style="display:grid;gap:var(--monster-space-3)">
  <monster-buy-box id="stock-buy-box"><span slot="title">Team license</span></monster-buy-box>
  <button id="stock-buy-box-update" type="button">Apply low stock</button>
</section>

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;
}

Customizing With Parts

You can adapt the visual appearance through exported parts instead of modifying the internal template. This reference is generated from the current component source.

The component exposes these part names:

actions: Container for the component actions.
base-price: Element representing the base price.
body: Element representing the body.
control: Outer wrapper of the component.
delivery: Element representing the delivery.
header: Header region.
list-price: Element representing the list price.
message: Status or guidance message.
price: Element representing the price.
prices: Element representing the prices.
quantity: Element representing the quantity.
quantity-control: Element representing the quantity control.
quantity-input: Element representing the quantity input.
quantity-label: Element representing the quantity label.
quantity-label-text: Element representing the quantity label text.
quantity-static: Element representing the quantity static.
quantity-unit: Element representing the quantity unit.
slots: Element representing the slots.
submit: Element representing the submit.
submit-label: Element representing the submit label.
sum: Element representing the sum.
tax: Element representing the tax.
total: Rendered total value.
total-label: Element representing the total label.
variants: Element representing the variants.
variants-control: Element representing the variants control.

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[]}

No description available.

getTag()

Returns

{string}

No description available.

Lifecycle methods

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

[assembleMethodSymbol]()

Returns

{BuyBox}

No description available.

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.