Form Multiselect

Description

<wui-form-multiselect> is a complete selecting solution. Specify options based on an array or array of objects

Single select

The basic single select / dropdown doesn’t require much configuration.

The options prop must be an Array.

Optional configuration flags (examples):

• :searchable="true" – enables the search functionality
• :close-on-select="false" – the dropdown stays open after selecting an option

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="['option1', 'option2', 'option3']"
    />
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: "",
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-basic.vue -->

Options (record data)

options is the dropdown data in array format, where each record (option) data are either just a string or keyed objects. Example format:

options as an array of Strings

const options = ["option1", "option2", "option3"];

options as an array of Objects

const options = [
  { age: 32, first_name: "Cyndi" },
  { age: 27, first_name: "Havij" },
  { age: 42, first_name: "Robert" },
];

Single select (object)

When working with objects, you must provide additional props: label and track-by.

track-by is used to identify the option within the options list thus it’s value has to be unique. In this example the key property is unique across all options, so it can be used as track-by value.

label is used to display the option.

Optional configuration flags (examples):

• :searchable="true" – enables the search functionality
• :allow-empty="false" – once there is a value it can’t be deselected

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      track-by="key"
      label="name"
      :searchable="true"
      :allow-empty="false"
      placeholder="Select an option"
    />
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: "",
        options: [
          { key: "option1", name: "Option 1" },
          { key: "option2", name: "Option 2" },
          { key: "option3", name: "Option 3" },
        ],
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-object.vue -->

Select with search

To enable the search you can set the prop searchable to true.

The internal search engine is based on the label prop. In other words – when searching, wui-form-multiselect only compares the option labels with the current search query. If you want to search inside other object properties look at the options provider function search example.

custom-label accepts a function with the option object as the first param. It should return a string which is then used to display a custom label.

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      :custom-label="nameWithLang"
      label="name"
      track-by="name"
      searchable
      placeholder="Select an option"
    />
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: { name: "Vue.js", language: "JavaScript" },
        options: [
          { name: "Vue.js", language: "JavaScript" },
          { name: "Rails", language: "Ruby" },
          { name: "Sinatra", language: "Ruby" },
          { name: "Laravel", language: "PHP" },
          { name: "Phoenix", language: "Elixir" },
        ],
      };
    },
    methods: {
      nameWithLang({ name, language }) {
        return `${name} — [${language}]`;
      },
    },
  };
</script>

<!-- wui-form-multiselect-single-select-search.vue -->

Multiple select

To allow multiple selections pass the :multiple="true" prop.

Optional configuration flags:

• :close-on-select="false" – the dropdown stays open after selecting an option
• :clear-on-select="false" – the search query stays the same after selecting an option

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      :multiple="true"
      :close-on-select="false"
      :clear-on-select="false"
      :preserve-search="true"
      placeholder="Pick some"
      label="name"
      track-by="name"
      :preselect-first="true"
    />
    <div class="m-t-5">Selected: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        options: ["option1", "option2", "option3"],
        value: "",
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-basic.vue -->

Table selects

To render the dropdown options as a table, you can set the :table="true".

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      table
      label="country"
      track-by="short_code"
    />
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: "",
        options: [
          { short_code: "DE", country: "Germany", region: "Europe" },
          { short_code: "CH", country: "Switzerland", region: "Europe" },
          { short_code: "AT", country: "Austria", region: "Europe" },
          { short_code: "FR", country: "France", region: "Europe" },
          { short_code: "PL", country: "Poland", region: "Europe" },
        ],
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-table.vue -->

When an array of Objects is provided, <wui-form-multiselect> automatically samples the first row to extract field names (the keys in the record data). Field names are automatically "humanized" by converting snake_case and camelCase to individual words and capitalizes each word. Example conversions:

• first_name becomes First Name
• last-name becomes Last-name
• age becomes Age
• YEAR remains YEAR
• isActive becomes Is Active

These titles will be displayed in the dropdown table header, in the order they appear in the first record of data. See the Fields section below for customizing how field headings appear.

Note: Field order is not guaranteed. Fields will typically appear in the order they were defined in the first row, but this may not always be the case depending on the version of browser in use. See section Fields (column definitions) below to see how to guarantee the order of fields, and to override the headings generated.

Fields (column definitions)

The fields prop is used to customize the dropdown table columns headings, and in which order the columns of data are displayed. The field object keys (i.e. country or region as shown below) are used to extract the value from each item (record) row.

Fields can be provided as a simple array or an array of objects. Internally the fields data will be normalized into the array of objects format. Events or slots that include the column field data will be in the normalized field object format (array of objects for fields, or an object for an individual field).

Fields as a simple array

Fields can be a simple array, for defining the order of the columns, and which columns to display:

Example: Using array fields definition

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      :fields="fields"
      table
      label="country"
      track-by="short_code"
    />
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: "",
        fields: ["country", "region", "short_code"],
        options: [
          { short_code: "DE", country: "Germany", region: "Europe" },
          { short_code: "CH", country: "Switzerland", region: "Europe" },
          { short_code: "AT", country: "Austria", region: "Europe" },
          { short_code: "FR", country: "France", region: "Europe" },
          { short_code: "PL", country: "Poland", region: "Europe" },
        ],
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-table-fields-as-array.vue -->

Fields as an array of objects

Fields can be a an array of objects, providing additional control over the fields (such as formatting, etc.). Only columns (keys) that appear in the fields array will be shown:

Example: Using array of objects fields definition

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      :fields="fields"
      table
      label="country"
      track-by="short_code"
    />
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: "",
        fields: [
          {
            key: "country",
            label: "Country",
          },
          {
            key: "region",
            label: "Region",
          },
          {
            key: "short_code",
            label: "Country code",
            class: "wui-bg-color--danger-20",
          },
        ],
        options: [
          { short_code: "DE", country: "Germany", region: "Europe" },
          { short_code: "CH", country: "Switzerland", region: "Europe" },
          { short_code: "AT", country: "Austria", region: "Europe" },
          { short_code: "FR", country: "France", region: "Europe" },
          { short_code: "PL", country: "Poland", region: "Europe" },
        ],
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-table-fields-as-objects.vue -->

Field definition reference

The following field properties are recognized:

Notes:

• Field properties, if not present, default to null (falsey) unless otherwise stated above.
• class, headerClass, cellClass etc. will not work with classes that are defined in scoped CSS, unless you are using VueLoader's Deep selector.
• For information on the syntax supported by headerStyle, see Class and Style Bindings in the Vue.js guide.
• Any additional properties added to the field definition objects will be left intact - so you can access them via the named scoped slots for custom data, header, and footer rendering.
• For information and usage about scoped slots and formatters, refer to the Custom Data Rendering section below.

Feel free to mix and match simple array and object array together:

const fields = [
  { key: "first_name", label: "First" },
  { key: "last_name", label: "Last" },
  "age",
  "sex",
];

Custom data rendering

Custom rendering for each data field in a row is possible using either scoped slots or a formatter callback function, or a combination of both.

Scoped option slots

You can use option() scoped slot to provide a custom option template. Look at the provided example for more details. Scoped option slots use the following naming syntax: 'option(' + field key + ')'.

You can use the default fall-back scoped slot 'option()' to format any dropdown option items that do not have an explicit scoped slot provided.

Example: Custom option data rendering with scoped slots

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      label="country"
      track-by="short_code"
    >
      <!-- A custom formatted option item -->
      <template #option(DE)="props"><strong>{ props.label }</strong></template>
      <!-- Optional default option scoped slot -->
      <template #option()="props">{ props.label }</template>
    </wui-form-multiselect>
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: "",
        options: [
          { short_code: "DE", country: "Germany", region: "Europe" },
          { short_code: "CH", country: "Switzerland", region: "Europe" },
          { short_code: "AT", country: "Austria", region: "Europe" },
          { short_code: "FR", country: "France", region: "Europe" },
          { short_code: "PL", country: "Poland", region: "Europe" },
        ],
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-scoped-option-slot.vue -->

The slot's scope variable (props in the above sample) will have the following properties:

Note:

• index will not always be the actual row's index number, as it is computed after filtering (search query) has been applied to the original options data. The index value will refer to the displayed row number.

Table custom rendering via scoped slots

In addition to the option() and option({key}) slots, it is also possible to provide custom rendering for the dropdown tables header and for a particular field.

Scoped field slot

Scoped field slots give you greater control over how the record data appears. You can use scoped slots to provided custom rendering for a particular field. If you want to add an extra field which does not exist in the records, just add it to the fields array, and then reference the field(s) in the scoped slot(s). Scoped field slots use the following naming syntax: 'cell(' + field key + ')'.

You can use the default fall-back scoped slot 'cell()' to format any cells that do not have an explicit scoped slot provided.

Example: Custom field data rendering with scoped slots

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      label="country"
      track-by="short_code"
    >
      <!-- A virtual column -->
      <template #cell(index)="data"> { data.index + 1 } </template>

      <!-- A custom formatted column -->
      <template #cell(country)="props">
        <b class="wui-color--active">{ props.value.toUpperCase() }</b>
      </template>

      <!-- A virtual composite column -->
      <template #cell(country_region)="props">
        { props.option.country } is in { props.option.region }
      </template>

      <!-- Optional default data cell scoped slot -->
      <template #cell()="props">
        <i>{ props.value }</i>
      </template>
    </wui-form-multiselect>
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: "",
        fields: [
          // A virtual column that doesn't exist in options
          "index",
          // A regular column
          "country",
          // A regular column
          "region",
          // A column that needs custom formatting
          { key: "short_code", label: "Country code" },
          // A virtual column made up from two fields
          { key: "country_region", label: "Country and region" },
        ],
        options: [
          { short_code: "DE", country: "Germany", region: "Europe" },
          { short_code: "CH", country: "Switzerland", region: "Europe" },
          { short_code: "AT", country: "Austria", region: "Europe" },
          { short_code: "FR", country: "France", region: "Europe" },
          { short_code: "PL", country: "Poland", region: "Europe" },
        ],
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-scoped-cell-slot.vue -->

The slot's scope variable (props in the above sample) will have the following properties:

Note:

• index will not always be the actual row's index number, as it is computed after filtering (search query) has been applied to the original options data. The index value will refer to the displayed row number.

Scoped header slot

Scoped slots for the header cells uses a special naming convention of 'head(<fieldkey>)'.

You can use a default fall-back scoped slot 'head()' to format any header cells that do not have an explicit scoped slot provided.

Example: Custom header cell rendering with scoped slots

<template>
  <div>
    <wui-form-multiselect
      v-model="value"
      :options="options"
      label="country"
      track-by="short_code"
    >
      <!-- A custom formatted data column cell -->
      <template #cell(country)="props">
        <strong>{ props.option.country }</strong>/ { props.option.region }
      </template>

      <!-- A custom formatted header cell for field 'country' -->
      <template #head(country)="props">
        <b class="wui-color--active">{ props.label.toUpperCase() }</b>
      </template>

      <!-- Default fall-back custom formatted header cell -->
      <template #head()="props">
        <i>{ props.label }</i>
      </template>
    </wui-form-multiselect>
    <div class="m-t-5">Value: { value }</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: "",
        fields: [
          // A regular column
          "country",
          // A column that needs custom formatting
          { key: "short_code", label: "Country code" },
        ],
        options: [
          { short_code: "DE", country: "Germany", region: "Europe" },
          { short_code: "CH", country: "Switzerland", region: "Europe" },
          { short_code: "AT", country: "Austria", region: "Europe" },
          { short_code: "FR", country: "France", region: "Europe" },
          { short_code: "PL", country: "Poland", region: "Europe" },
        ],
      };
    },
  };
</script>

<!-- wui-form-multiselect-single-select-scoped-cell-slot.vue -->

The slot's scope variable (props in the above sample) will have the following properties:

Infinite scrolling

<wui-form-multiselect> displays a maximum of 20 options. If more than 20 options are passed through, the component automatically activates infinite scrolling.

Example 1 - providing an array with 50 options

You have an array with 50 options:

const options = {
  options: [
    { value: "value_1", text: "Value 1" },
    //  ... all other 48 options go here
    { value: "value_50", text: "Value 50" },
  ],
};

Once the dropdown menu opens, only the first 20 options are shown to the user (only 20 items are rendered in HTML). As soon as the user starts scrolling and gets to the end of the list, another 20 options from the already existing options array are rendered and displayed.

Example 2 - using a provider function

Instead of an array, you use a provider function, which returns an array of 1000 options.

const options = {
  options: (ctx) => {
    // Sample function that makes an API call and returns 1000 items
    // return [...1000 items]
  },
};

As in example 1, only the first 20 options are displayed here. As soon as the user starts scrolling and gets to the end of the list, another 20 options from the already existing array are revealed.

Note: the provider function is not called again on infinite scrolling as long as the dropdown menu is open unless you set providerPaging to true. The provider function is only called when the dropdown menu opens or the user changes the search term.

Using options provider function

As mentioned, it is possible to use a function to provide the select options, by specifying a function reference via the options prop.

The provider function is called with the following signature:

provider(ctx, [callback]);

The ctx is the context object associated with the editor's state, and contains the following properties:

The second argument callback is an optional parameter for when using the callback asynchronous method.

Example: returning an array of filter options (synchronous):

function myProvider() {
  let options = [];

  // Perform any options processing needed

  // Must return an array
  return options || [];
}

Example: Using a Promise to return data (asynchronous):

function myProvider(ctx) {
  const promise = axios.get(`/some/url?query=${ctx.query}`);
  // or with pagination
  // const promise = axios.get(
  //   `/some/url?query=${ctx.query}&offset=${ctx.offset}&limit=${ctx.limit}`
  // );

  // Must return a promise that resolves to an array of options
  return promise.then((data) => {
    // Pluck the array of options off our axios response
    const options = data.options;
    // Must return an array of options or an empty array if an error occurred
    return options || [];
  });
}

Example: Using an async function (semi-synchronous):

async function myProvider(ctx) {
  try {
    const response = await axios.get(`/some/url?query=${ctx.query}`);
    // or with pagination
    // const response = await axios.get(`/some/url?query=${ctx.query}&offset=${ctx.offset}&limit=${ctx.limit});
    return response.items;
  } catch (error) {
    return [];
  }
}

Note: The options provider function is called every time the dropdown menu opens.

Options provider paging and filtering

By default, the options provider function is responsible for filtering the data, before passing it to the form-multiselect for display.

You can enable provider paging by setting the providerPaging prop to true.

The provider function is triggered as soon as:

• the dropdown menu opens (usually when displayed to the user)
• the user enters a term in the search field (searchable must be set to true).
• the end of the list ist reached by scrolling down and there are no items left to reveal (when :provider-paging="true")

Component reference

<wui-form-multiselect>

• <wui-form-multiselect> Component aliases
• <wui-form-multiselect> Properties
• <wui-form-multiselect> v-model
• <wui-form-multiselect> Slots
• <wui-form-multiselect> Events

Component aliases

<wui-form-multiselect> can also be used via the following aliases:

• <wui-multiselect>

Properties

v-model

Slots

Events

Importing individual components

You can import individual components into your project via the following named exports:

Example

import { WuiFormMultiselect } from "@wui/wui-vue/lib/form-multiselect";
Vue.component("wui-form-multiselect", WuiFormMultiselect);

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Example

import { FormMultiselectPlugin } from "@wui/wui-vue/lib/form-multiselect";
Vue.use(FormMultiselectPlugin);