Select

Storybook GitHub

<script setup lang="ts">
import { ref } from "vue";
import MtSelect from "@shopware-ag/meteor-component-library/MtSelect";

const options = [
  { id: 1, label: "Option A", value: "a" },
  { id: 2, label: "Option B", value: "b" },
  { id: 3, label: "Option C", value: "c" },
];

const selectedValue = ref("b");
</script>

<template>
  <mt-select v-model="selectedValue" label="Select" :options="options" />
</template>

Usage

Select lets users pick one or more values from a list of predefined options instead of entering free-form text. Use it when the list may be longer than a simple inline choice group would comfortably show, or when searching, custom option labels, or multi selection would improve the picking experience.

import { MtSelect } from "@shopware-ag/meteor-component-library";

Examples

Multiple selection

Enable enableMultiSelection so users can choose several values at once.

<script setup lang="ts">
import { ref } from "vue";
import MtSelect from "@shopware-ag/meteor-component-library/MtSelect";

const options = [
  { id: 1, label: "Option A", value: "a" },
  { id: 2, label: "Option B", value: "b" },
  { id: 3, label: "Option C", value: "c" },
];

const selectedValues = ref(["a", "c"]);
</script>

<template>
  <mt-select
    v-model="selectedValues"
    label="Select multiple options"
    :enable-multi-selection="true"
    :options="options"
  />
</template>

Many selected values

valueLimit caps how many selected values are shown as tags. The remaining ones collapse into a counter that expands the full list when clicked.

<script setup lang="ts">
import { ref } from "vue";
import MtSelect from "@shopware-ag/meteor-component-library/MtSelect";

const options = [
  { id: 1, label: "Shoes", value: "shoes" },
  { id: 2, label: "Clothing", value: "clothing" },
  { id: 3, label: "Accessories", value: "accessories" },
  { id: 4, label: "Sportswear", value: "sportswear" },
  { id: 5, label: "Bags", value: "bags" },
  { id: 6, label: "Jewelry", value: "jewelry" },
  { id: 7, label: "Watches", value: "watches" },
  { id: 8, label: "Eyewear", value: "eyewear" },
];

const selectedValues = ref([
  "shoes",
  "clothing",
  "accessories",
  "sportswear",
  "bags",
  "jewelry",
]);
</script>

<template>
  <mt-select
    v-model="selectedValues"
    label="Categories"
    :enable-multi-selection="true"
    :value-limit="3"
    :options="options"
  />
</template>

Small

small renders the compact variant with a lower field height and smaller tags, for toolbars and other tight layouts.

<script setup lang="ts">
import { ref } from "vue";
import MtSelect from "@shopware-ag/meteor-component-library/MtSelect";

const options = [
  { id: 1, label: "Shoes", value: "shoes" },
  { id: 2, label: "Clothing", value: "clothing" },
  { id: 3, label: "Accessories", value: "accessories" },
  { id: 4, label: "Sportswear", value: "sportswear" },
  { id: 5, label: "Bags", value: "bags" },
];

const selectedValues = ref(["shoes", "accessories"]);
</script>

<template>
  <mt-select
    v-model="selectedValues"
    label="Categories"
    small
    :enable-multi-selection="true"
    :options="options"
  />
</template>

API reference

Props

Prop	Type	Default
`options` * An array of objects with the labelProperty and valueProperty.	`unknown[]`
`disabled` Disables or enables the select field.	`false \| true`	`false`
`label` The label for the select field itself.	`string`	`""`
`placeholder` The placeholder for the select field.	`string`	`""`
`error` An error in your business logic related to this field. For example: {"code": 500, "detail": "Error while saving"}	`Record<string, any>`	`null`
`is-inherited` Toggles the inheritance visualization.	`false \| true`	`false`
`is-inheritance-field` Determines if the field is inheritable.	`false \| true`	`false`
`hint` Optional caption below the field. The `#hint` slot takes precedence when provided.	`string \| null`	`null`
`model-value` Dependent on multiSelection, either a single value or an array of values.	`string \| number \| boolean \| object \| unknown[] \| null`	`null`
`small` Render the select field in small	`false \| true`	`false`
`disable-inheritance-toggle` Determines the active state of the inheritance toggle.	`false \| true`	`false`
`is-loading` Toggles the loading state of the select field.	`false \| true`	`false`
`label-property` The object key of the label property. Can be a single string or an array of strings. If an array is provided, the first property that has a non-empty value will be used.	`string \| string[]`	`"label"`
`value-property` The object key to use for the value.	`string`	`"value"`
`enable-search` Toggles the search input. When disabled, the input is rendered readonly, which also keeps browsers from treating it as an autofillable field.	`false \| true`	`true`
`always-show-placeholder` Determines if the placeholder should be shown even when there are no selections.	`false \| true`	`true`
`enable-multi-selection` Toggles if either one or more items can be selected.	`false \| true`	`false`
`value-limit` The number of items that are expanded by default.	`number`	`5`
`hide-clearable-button` Toggles a button to clear all selections.	`false \| true`	`false`
`highlight-search-term` Determines to highlight the searched term or not.	`false \| true`	`true`
`search-function` Used to implement a custom search function. Parameters passed: { options, labelProperty, valueProperty, searchTerm }	`Function`	({ options, labelProperty, searchTerm, }: { options: any; labelProperty: string \| string[]; searchTerm: string; }) => { return options.filter((option: any) => { // If labelProperty is an array, check each property if (Array.isArray(labelProperty)) { for (const property of labelProperty) { const label = getPropertyValue(option, property); if (label && typeof label === "string" && label.toLowerCase().includes(searchTerm.toLowerCase())) { return true; } } return false; } // Original behavior for string labelProperty const label = getPropertyValue(option, labelProperty); if (!label) { return false; } return label.toLowerCase().includes(searchTerm.toLowerCase()); }); }
`on-update:model-value`	`((...args: any[]) => any) \| undefined`
`on-change`	`((...args: any[]) => any) \| undefined`
`on-inheritance-remove`	`((...args: any[]) => any) \| undefined`
`on-inheritance-restore`	`((...args: any[]) => any) \| undefined`
`on-item-add`	`((...args: any[]) => any) \| undefined`
`on-item-remove`	`((...args: any[]) => any) \| undefined`
`on-display-values-expand`	`((...args: any[]) => any) \| undefined`
`on-paginate`	`((...args: any[]) => any) \| undefined`
`on-search-term-change`	`((...args: any[]) => any) \| undefined`

Exposed

Name	Type
`t`	`ComposerTranslation<{ en: { messageNoResults: string; }; de: { messageNoResults: string; }; }, "en" \| "de", RemoveIndexSignature<{ [x: string]: LocaleMessageValue<VueMessageType>; }>, never, "messageNoResults", "messageNoResults">`
`getKey`	`any`
`searchTerm`	`string`
`limit`	`number`
`searchResults`	`never[]`
`isSearchResultsLoading`	`boolean`
`showFieldHint`	`boolean`
`visibleValues`	`any[]`
`totalValuesCount`	`number`
`invisibleValueCount`	`number`
`currentValue`	`string \| number \| boolean \| object \| unknown[] \| null`
`visibleResults`	`any[]`
`isSmall` `size="small"` passed as an attribute reaches mt-base-field through $attrs; treat it like the `small` prop so both render the same small select.	`boolean`
`componentClasses`	`Record<string, boolean>`

Best practices

Use a clear field label so users understand what they are choosing.
Keep option labels concise and easy to scan.
Use enableMultiSelection only when selecting multiple values is a real user need.
Set labelProperty and valueProperty explicitly when your option shape differs from the defaults.
Add hint or help text when the selection rules need extra explanation.

Don't

Do not use Select when users should enter arbitrary text instead of choosing from known values.
Do not use a long select list when a smaller visible choice group would be easier to compare directly.
Do not rely on placeholder text as the only instruction for the field.
Do not mix unclear or duplicated option labels, especially in searchable lists.
Do not enable multi selection when the form should store exactly one value.

Behavior

Select supports both single and multiple selection. modelValue can be a single value, an option object, or an array depending on the selection mode and valueProperty.
The component searches within the provided options by default and supports a custom searchFunction when filtering needs to follow business-specific rules.
labelProperty can be a string or an array of property paths. When an array is used, the first non-empty value is used as the visible label.
Shared field features such as hint, error, prefix and suffix content, and inheritance handling work the same way as in other form fields.
small renders a compact variant, which is better suited to tighter layouts.
enableSearch toggles the inline search input. Disabling it renders the field read-only for typing, which also keeps browsers and password managers from offering autofill in the search input.
Use selectionLabelProperty to customize how selected items are rendered in the closed field.
Use the result-item slot or resultLabelProperty when result rows need richer formatting than a plain text label.
Use the before-item-list and after-item-list slots for supporting content around the result list, such as guidance or actions.

Accessibility

Provide a clear field label or other nearby visible context so users understand what the selection controls.
Keep option labels distinct so users can tell similar choices apart while searching or navigating with the keyboard.
Use help text when multiple selection, custom option rendering, or inherited values might otherwise be unclear.

Radio Group: when a small set of options should stay visible so users can compare them directly.
Checkbox: when users are toggling independent options on and off rather than choosing from a shared option set.

Edit this pageorReport an issue

A lightweight input for filtering or finding content in a list, table, or page section.

Skeleton Bar

A shimmering placeholder block that holds layout while content loads.