BuyBox

Product buy box control with variants, quantity, pricing, and add-to-cart.

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-buy-box control combines product configuration, variant selection, quantity, pricing, and add-to-cart into a single, cohesive UI. It supports static configuration as well as data sourced from REST endpoints through a datasource and mapping options.

Key Features

Variant selection: Uses monster-variant-select internally, including row selects and combined select layouts.
Pricing logic: Handles price, list price, base price, currency, tax rate, and quantity-based tiers.
Quantity rules: Supports min/max, step, and allowed ranges (including open ranges).
Cart integration: Posts payloads directly or forwards them to a shared monster-cart-control.
Remote mapping: Maps product, variant, and pricing fields from API responses with path templates.

Variants

Variants are configured through the variants option. Define dimensions (such as size and color) and provide data rows that represent each SKU.

Pricing

Pricing can be defined globally or per-variant. When per-variant pricing is present, the buy box switches pricing fields based on the selected SKU. Tier pricing can be used to apply volume discounts by quantity.

Data Sources

The buy box can fetch product, stock, or pricing data from endpoints via a datasource. Mapping options allow adapting different API shapes without changing the UI logic.

Cart Flow

When the user submits the buy box, a payload is created from the current selection. The payload can be sent directly to the configured cart URL or routed through a cart control for shared cart state and optimistic UI feedback.

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

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 **/

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.