Exact exports, props, slots, hooks, and runtime behavior belong to SDK package reference. Examples are guidance unless explicitly marked copy-paste-safe.

Review component intent and composition guidance before wiring this component into an app. Then use the live playground to confirm the rendered behavior.

Playground

• Import path: @enadhq/enad-react-sdk/client/storefront.
• Live playground: /components/commerce/variant-selector.

When to use it

Use VariantSelector when the product has one or more structured option axes and the visitor needs to make a valid combination before purchasing.

It is especially useful when unavailable or low-stock choices need to stay visible but clearly marked.

Composition notes

axes defines the option groups, selected holds the current per-axis choice, and onChange updates a single axis at a time. Keep axis names stable because they are the keys in the selection map.

Each option can also carry:

• state — available, low-stock, out-of-stock, or unavailable
• meta — short supporting copy such as "Few left" or "Back soon"

When the product model is more complex, make sure the selector state stays tightly connected to inventory and variant-resolution logic.

Behavior and theming guidance

Unavailable options should still explain the range without pretending to be silently removed. Use state and meta when the storefront needs to signal low stock, upcoming restocks, or store-only availability while keeping the selection surface stable.

Use the optional labels object when the state messaging needs to match the storefront tone.

Keep option labels short and consistent. Long or mixed naming makes multi-axis selection feel harder than it is.

Connected companion

Use VariantSelector when the page already owns the variant axes, the selected state, and the variant-resolution logic.

Use SearchProductVariantSelector from @enadhq/enad-react-sdk/client/search when the page wants the SDK to resolve a search-backed product and drive the variant-selection model for the existing presentational selector.

Review notes

These notes define scoped usage boundaries without claiming exact prop or runtime truth beyond SDK package reference.

VariantSelector stays controlled option-selection UI. The component can display axes, selected values, option state, and short metadata; the caller owns variant resolution, inventory truth, purchase eligibility, and cart handoff.

• Keep axis keys stable because they are the selection contract between the selector and product logic.
• Keep unavailable or out-of-stock options visible when they help shoppers understand the range, but make the state explicit with labels and metadata.
• Do not treat option selection as add-to-cart behavior; resolve the concrete purchasable variant before the purchase action runs.

Contract scope

• Use SDK package reference for exact props, exports, slots, hooks, and runtime behavior.
• Public import: @enadhq/enad-react-sdk/client/storefront.
• Playground route: /sandbox?component=VariantSelector.
• Copy/paste scope: guidance-only. Treat examples as guidance until checked against SDK package reference.

Implementation notes

• VariantSelector is controlled selection state with stable axes; do not let option order or labels drift between renders.