Skip to main content

BundleProductAttributeController

You get this controller when useAttribute(...) resolves a bundle product attribute. A bundle attribute lets a shopper add other products to the configuration, optionally with per-value quantities, and supports single- or multi-select behavior.

import { useAttribute } from "@expivi/product-configurator";

const attribute = useAttribute(configurator, attributeCid);

Selecting bundle items and adjusting quantity​

Toggle a value with setValue(cid). For multi-select bundles, raise or lower the per-value quantity.

const item = attribute.allValues[0];

if (attribute.canChangeValueState(item)) {
  attribute.setValue(item.cid); // toggles selection
}

if (attribute.isValueSelected(item.cid)) {
  attribute.incrementQuantity(item.cid);
  attribute.decrementQuantity(item.cid);
}

API​

settings​

The raw bundle settings object.

isBundle: boolean​

Always true.

isMandatory: boolean​

Whether settings.mandatory is true. A mandatory bundle cannot be reduced to an empty selection.

canChangeValueState(value): boolean​

Whether the given value can be toggled. Returns false for static attributes, and false when unselecting the last remaining value of a mandatory bundle.

isValueSelected(cid): boolean​

Whether the value with this cid is currently selected.

getSelectedValues(): BundleProductAttributeValueType[]​

The selected bundle values resolved against the current attribute values.

setValue(cid): void​

Toggles selection. Multi-select bundles add/remove the value; single-select bundles replace the current selection (or clear it when allowed). Overrides the base so selection can be intercepted via registerBeforeSetValue(...) — see the Common Attribute API.

incrementQuantity(cid): void​

Increments the quantity of a selected value by 1. No-op for static or single-select bundles. Honors a registerBeforeIncrementValue(...) interceptor when registered.

decrementQuantity(cid): void​

Decrements the quantity of a selected value by 1 (never below 0).

Adjacent-product connections​

For bundles that connect to an adjacent-add target, these members drive the connection-candidate UI:

connectionCandidateValueCids: string[]​

Cids of this attribute's values that can connect to the currently-selected adjacent-add target. Empty when no target is active.

cancelConnectionTargetIfActive(): boolean​

Clears an active adjacent-add target. Returns true if a target was active.

registerOnConnectionCandidateSelect(handler) / unregisterOnConnectionCandidateSelect()​

Register or remove a handler invoked when a connection candidate is selected. subscribe(...) also re-fires on adjacent-product changes so the UI re-renders candidates.

triggerConnectionCandidateSelect(valueCid): boolean​

Fires the registered handler for the value and clears the target once it resolves. Returns true if a handler was registered.

Behavior notes​

  • When selected values become disallowed by rules, the controller unselects them and raises a warning message with an "Undo" action.

For all other members, see the Common Attribute API.