VariantSelect

A control to pick valid variant combinations (e.g., color/size).

Import

import { VariantSelect } from "@schukai/monster/source/components/form/variant-select.mjs";

Source

View source code

Package

@schukai/monster

Since

4.64.0

Introduction

The monster-variant-select control helps users select valid product variants across multiple dimensions such as color, size, and fit. It can render per-dimension buttons, per-dimension selects, or a combined select of all variants.

Basic Usage

<monster-variant-select data-monster-options='{&n
  "data": [
    { "id": "sku-1", "color": "Red", "size": "S" },
    { "id": "sku-2", "color": "Red", "size": "M" },
    { "id": "sku-3", "color": "Blue", "size": "S" }
  ],
  "dimensions": [
    { "key": "color", "label": "Color" },
    { "key": "size", "label": "Size" }
  ]
}'></monster-variant-select>

Returned Value

When all dimensions form a valid variant, value is set to the variant id. If the selection is incomplete or invalid, value is null.

Remote Data

Variants can be loaded from a URL using the mapping options.

control.setOption("url", "/assets/examples/variants.json");
control.setOption("mapping.selector", "items");
control.setOption("mapping.valueTemplate", "${id}");

Button Layout

Basic button-based variant selection for two dimensions.

Javascript

import '@schukai/monster/source/components/form/variant-select.mjs';

const control = document.getElementById('variant-select-buttons');

control.setOption('data', [
    { id: 'sku-1', color: 'Red', size: 'S' },
    { id: 'sku-2', color: 'Red', size: 'M' },
    { id: 'sku-3', color: 'Blue', size: 'S' }
]);

control.setOption('dimensions', [
    { key: 'color', label: 'Color' },
    { key: 'size', label: 'Size' }
]);

control.refresh();

HTML

<monster-variant-select id="variant-select-buttons"></monster-variant-select>

Stylesheet

/** no additional stylesheet is defined **/

Row Selects

Per-dimension selects for color, size, and fit using features.rowSelects.

Javascript

import '@schukai/monster/source/components/form/variant-select.mjs';

const control = document.getElementById('variant-select-row');

control.setOption('data', [
    { id: 'sku-1', color: 'Red', size: 'S', fit: 'Regular' },
    { id: 'sku-2', color: 'Red', size: 'M', fit: 'Regular' },
    { id: 'sku-3', color: 'Blue', size: 'S', fit: 'Slim' }
]);

control.setOption('dimensions', [
    { key: 'color', label: 'Color' },
    { key: 'size', label: 'Size' },
    { key: 'fit', label: 'Fit' }
]);

control.setOption('features.rowSelects', true);

control.refresh();

HTML

<monster-variant-select id="variant-select-row"></monster-variant-select>

Stylesheet

/** no additional stylesheet is defined **/

Combined Select

Combined select with all variants. Uses a custom label template for the dropdown.

Javascript

import '@schukai/monster/source/components/form/variant-select.mjs';

const control = document.getElementById('variant-select-combined');

control.setOption('data', [
    { id: 'sku-1', color: 'Red', size: 'S' },
    { id: 'sku-2', color: 'Red', size: 'M' },
    { id: 'sku-3', color: 'Blue', size: 'S' }
]);

control.setOption('dimensions', [
    { key: 'color', label: 'Color' },
    { key: 'size', label: 'Size' }
]);

control.setOption('features.rowSelects', true);
control.setOption('features.combinedSelect', true);
control.setOption('layout.combineSelect', true);
control.setOption('mapping.labelTemplate', '${id} - ${color} / ${size}');

control.refresh();

HTML

<monster-variant-select id="variant-select-combined"></monster-variant-select>

Stylesheet

/** no additional stylesheet is defined **/

Label Templates

Separate keys from display labels using valueTemplate and labelTemplate per dimension.

Javascript

import '@schukai/monster/source/components/form/variant-select.mjs';

const control = document.getElementById('variant-select-label-template');

control.setOption('data', [
    { id: 'sku-1', colorKey: 'red', colorLabel: 'Rot', sizeKey: 's', sizeLabel: 'Small' },
    { id: 'sku-2', colorKey: 'red', colorLabel: 'Rot', sizeKey: 'm', sizeLabel: 'Medium' },
    { id: 'sku-3', colorKey: 'blue', colorLabel: 'Blau', sizeKey: 's', sizeLabel: 'Small' }
]);

control.setOption('dimensions', [
    {
        key: 'colorKey',
        label: 'Farbe',
        valueTemplate: '${colorKey}',
        labelTemplate: '${colorLabel}'
    },
    {
        key: 'sizeKey',
        label: 'Grosse',
        valueTemplate: '${sizeKey}',
        labelTemplate: '${sizeLabel}'
    }
]);

control.refresh();

HTML

<monster-variant-select id="variant-select-label-template"></monster-variant-select>

Stylesheet

/** no additional stylesheet is defined **/

Values Map

Map raw values to labels with the values object per dimension.

Javascript

import '@schukai/monster/source/components/form/variant-select.mjs';

const control = document.getElementById('variant-select-values-map');

control.setOption('data', [
    { id: 'sku-1', color: 'red', size: 's' },
    { id: 'sku-2', color: 'red', size: 'm' },
    { id: 'sku-3', color: 'blue', size: 's' }
]);

control.setOption('dimensions', [
    {
        key: 'color',
        label: 'Color',
        values: {
            blue: 'Blue',
            red: 'Red'
        }
    },
    {
        key: 'size',
        label: 'Size',
        values: {
            s: 'Small',
            m: 'Medium'
        }
    }
]);

control.refresh();

HTML

<monster-variant-select id="variant-select-values-map"></monster-variant-select>

Stylesheet

/** no additional stylesheet is defined **/

Messages Off

Disable status messages with features.messages.

Javascript

import '@schukai/monster/source/components/form/variant-select.mjs';

const control = document.getElementById('variant-select-messages-off');

control.setOption('data', [
    { id: 'sku-1', color: 'Red', size: 'S' },
    { id: 'sku-2', color: 'Red', size: 'M' }
]);

control.setOption('dimensions', [
    { key: 'color', label: 'Color' },
    { key: 'size', label: 'Size' }
]);

control.setOption('features.messages', false);

control.refresh();

HTML

<monster-variant-select id="variant-select-messages-off"></monster-variant-select>

Stylesheet

/** no additional stylesheet is defined **/

Remote Data

Load variants from /assets/examples/variants.json and map the response with mapping.selector.

Javascript

import '@schukai/monster/source/components/form/variant-select.mjs';

const control = document.getElementById('variant-select-remote');

control.setOption('url', '/assets/examples/variants.json');
control.setOption('mapping.selector', 'items');
control.setOption('mapping.valueTemplate', '${id}');
control.setOption('mapping.labelTemplate', '${id} - ${color} / ${size}');

control.setOption('dimensions', [
    { key: 'color', label: 'Color' },
    { key: 'size', label: 'Size' },
    { key: 'fit', label: 'Fit' }
]);

control.refresh();

HTML

<monster-variant-select id="variant-select-remote"></monster-variant-select>

Stylesheet

/** no additional stylesheet is defined **/

Component Design

The control renders rows for each dimension and optionally a combined select. Styling hooks are exposed via exported parts for the container and message area.

control: Main wrapper of the variant select.
rows: Container for dimension rows.
row: Single dimension row.
message: Status message area.

monster-variant-select::part(control) {
    padding: 0.5rem;
}

monster-variant-select::part(message) {
    font-size: 0.9rem;
}

HTML Structure

<monster-variant-select></monster-variant-select>

JavaScript Initialization

const element = document.createElement('monster-variant-select');
document.body.appendChild(element);

Exported

VariantSelect

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

dimensions

array<object>

undefined

Dimension definitions ({key, label, presentation, valueTemplate, labelTemplate})

dimensions.values

array<object>|object|null

undefined

Optional label map for a dimension

data

array<object>

undefined

Variant items

url

string|null

Endpoint to fetch variants

fetch

object

Fetch options (method, headers, body)

mapping

object

Data mapping for fetched results

mapping.selector

string

hed data

mapping.valueTemplate

string

Template for variant value

mapping.labelTemplate

string

Template for combined variant label

mapping.filter

function|null

Filter function

layout

object

Layout options

layout.autoSelect

boolean

true

do not fit

layout.buttonMinWidth

number

imate button layout

features

object

Feature toggles

features.messages

boolean

true

messages

object

undefined

Message text

messages.valid

string

undefined

Message for valid selection

messages.invalid

string

undefined

Message for invalid selection

messages.incomplete

string

undefined

Message for incomplete selection

actions

object

Callback actions

actions.onchange

function

called on any selection change

actions.onvalid

function

called when a valid variant is selected

actions.oninvalid

function

called when selection becomes invalid

actions.onlazyload

function

called before fetching variants

actions.onlazyloaded

function

called after fetching variants

actions.onlazyerror

function

called on fetch errors

classes

object

CSS classes

classes.option

string

monster-button-outline-primary

Base class for option buttons

classes.optionSelected

string

is-selected

Class for selected options

classes.optionDisabled

string

is-disabled

Class for disabled options

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()

Reload the data from data or url.

State query methods

value()

Returns

{string|null}

value(value)

Parameters

value {string|null}: value

Static methods

[instanceSymbol]()

Returns

{symbol}

This method is called by the instanceof operator.

formAssociated()

Returns

{boolean}

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

{VariantSelect}

Events

The component emits the following events:

monster-variant-select-change
monster-variant-select-valid
monster-variant-select-invalid
monster-variant-select-lazy-load
monster-variant-select-lazy-loaded
monster-variant-select-lazy-error

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.