MultiSelect

The MultiSelect component allows users to select multiple options from a list with a dropdown. Typing filters the list to make selections from a large list easier. It can also be used without an options list if the creation of arbitrary tags is desired.

Usage

To use MultiSelect, setup v-model as an array and pass in your options array as an array of objects. See the Select docs for more information about how to create options.

See the Form Field docs for more information about labeling, descriptions, placeholders, error state, success state and more.

<template>
  <ci-multi-select
    v-model="states"
    :options="options"
    sublabel="Options"
    placeholder="Select an option"
  />
</template>
<script>
export default {
  data() {
    return {
      states: [],
      options: [
        { value: 1, text: 'Option 1', },
        { value: 2, text: 'Option 2', },
        { value: 3, text: 'Option 3', },
        { value: 4, text: 'Option 4', },
        { value: 5, text: 'Option 5', },
      ]
    }
  }
}
</script>

Select All Option

Use the select-all-text prop to pass in a string for your select all option. When present, the first item in the dropdown will be a select all option with the text provided. Clicking this option will select all items in the dropdown. The select all option is only visible when the user hasn't filtered the list with the input.

<template>
  <ci-multi-select
    v-model="states"
    :options="options"
    sublabel="States"
    placeholder="Select a state"
    select-all-text="Select all states"
    fullwidth
  />
</template>
<script>
export default {
  data() {
    return {
      states: [],
      options: [
        { value: 'AL', text: 'Alabama', },
        { value: 'AK', text: 'Alaska', },
        { value: 'AZ', text: 'Arizona', },
        { value: 'AR', text: 'Arkansas', },
        { value: 'CA', text: 'California', },
        { value: 'CO', text: 'Colorado', },
        { value: 'CT', text: 'Connecticut', },
        { value: 'DE', text: 'Delaware', },
        { value: 'FL', text: 'Florida', },
        { value: 'GA', text: 'Georgia', },
        { value: 'HI', text: 'Hawaii', },
        { value: 'ID', text: 'Idaho', },
        { value: 'IL', text: 'Illinois', },
        { value: 'IN', text: 'Indiana', },
        { value: 'IA', text: 'Iowa', },
        { value: 'KS', text: 'Kansas', },
        { value: 'KY', text: 'Kentucky', },
        { value: 'LA', text: 'Louisiana', },
        { value: 'ME', text: 'Maine', },
        { value: 'MD', text: 'Maryland', },
        { value: 'MA', text: 'Massachusetts', },
        { value: 'MI', text: 'Michigan', },
        { value: 'MN', text: 'Minnesota', },
        { value: 'MS', text: 'Mississippi', },
        { value: 'MO', text: 'Missouri', },
        { value: 'MT', text: 'Montana', },
        { value: 'NE', text: 'Nebraska', },
        { value: 'NV', text: 'Nevada', },
        { value: 'NH', text: 'New Hampshire', },
        { value: 'NJ', text: 'New Jersey', },
        { value: 'NM', text: 'New Mexico', },
        { value: 'NY', text: 'New York', },
        { value: 'NC', text: 'North Carolina', },
        { value: 'ND', text: 'North Dakota', },
        { value: 'OH', text: 'Ohio', },
        { value: 'OK', text: 'Oklahoma', },
        { value: 'OR', text: 'Oregon', },
        { value: 'PA', text: 'Pennsylvania', },
        { value: 'RI', text: 'Rhode Island', },
        { value: 'SC', text: 'South Carolina', },
        { value: 'SD', text: 'South Dakota', },
        { value: 'TN', text: 'Tennessee', },
        { value: 'TX', text: 'Texas', },
        { value: 'UT', text: 'Utah', },
        { value: 'VT', text: 'Vermont', },
        { value: 'VA', text: 'Virginia', },
        { value: 'WA', text: 'Washington', },
        { value: 'WV', text: 'West Virginia', },
        { value: 'WI', text: 'Wisconsin', },
        { value: 'WY', text: 'Wyoming', },
      ]
    }
  }
}
</script>

Pasting options

A user can paste strings split by commas into input field, for example, Alabama, Alaska. Pasted strings will be checked against the textKey for options in the multiselect and aren't case sensitive. Strings that match an option will be added as tags.

String that do not match an option will be left in the input as text and emitted as an @error event if allowCustomValues is false. You can leverage this event to show an error, as shown here. Try pasting Albama, alaska, Arizona, Califrnia below:

<template>
  <ci-multi-select
    v-model="states"
    :options="options"
    sublabel="States"
    placeholder="Select a state"
    select-all-text="Select all states"
    fullwidth
    :error="error"
    @error="showError($event)"
  />
</template>
<script>
export default {
  data() {
    return {
      error: false,
      states: [],
      options: [
        { value: 'AL', text: 'Alabama', },
        { value: 'AK', text: 'Alaska', },
        { value: 'AZ', text: 'Arizona', },
        { value: 'AR', text: 'Arkansas', },
        { value: 'CA', text: 'California', },
        { value: 'CO', text: 'Colorado', },
        { value: 'CT', text: 'Connecticut', },
        { value: 'DE', text: 'Delaware', },
        { value: 'FL', text: 'Florida', },
        { value: 'GA', text: 'Georgia', },
        { value: 'HI', text: 'Hawaii', },
        { value: 'ID', text: 'Idaho', },
        { value: 'IL', text: 'Illinois', },
        { value: 'IN', text: 'Indiana', },
        { value: 'IA', text: 'Iowa', },
        { value: 'KS', text: 'Kansas', },
        { value: 'KY', text: 'Kentucky', },
        { value: 'LA', text: 'Louisiana', },
        { value: 'ME', text: 'Maine', },
        { value: 'MD', text: 'Maryland', },
        { value: 'MA', text: 'Massachusetts', },
        { value: 'MI', text: 'Michigan', },
        { value: 'MN', text: 'Minnesota', },
        { value: 'MS', text: 'Mississippi', },
        { value: 'MO', text: 'Missouri', },
        { value: 'MT', text: 'Montana', },
        { value: 'NE', text: 'Nebraska', },
        { value: 'NV', text: 'Nevada', },
        { value: 'NH', text: 'New Hampshire', },
        { value: 'NJ', text: 'New Jersey', },
        { value: 'NM', text: 'New Mexico', },
        { value: 'NY', text: 'New York', },
        { value: 'NC', text: 'North Carolina', },
        { value: 'ND', text: 'North Dakota', },
        { value: 'OH', text: 'Ohio', },
        { value: 'OK', text: 'Oklahoma', },
        { value: 'OR', text: 'Oregon', },
        { value: 'PA', text: 'Pennsylvania', },
        { value: 'RI', text: 'Rhode Island', },
        { value: 'SC', text: 'South Carolina', },
        { value: 'SD', text: 'South Dakota', },
        { value: 'TN', text: 'Tennessee', },
        { value: 'TX', text: 'Texas', },
        { value: 'UT', text: 'Utah', },
        { value: 'VT', text: 'Vermont', },
        { value: 'VA', text: 'Virginia', },
        { value: 'WA', text: 'Washington', },
        { value: 'WV', text: 'West Virginia', },
        { value: 'WI', text: 'Wisconsin', },
        { value: 'WY', text: 'Wyoming', },
      ]
    }
  },
  methods: {
    showError(text) {
      this.error = `The pasted value(s) "${text}" are not states.`;
    }
  }
}
</script>

Loading

Pass a boolean into the loading prop to add a loading state to the component. The boolean hides and shows a Loading Spinner). This can be useful if you need to fetch options asynchronously.

In this demo we mock fetching options when the multi-select is opened.

<template>
  <div>
    <ci-multi-select
      v-model="selectedPeople"
      :options="people"
      :loading="isLoading"
      sublabel="People"
      fullwidth
      @open="fetchPeople"
    />
    <br><br>
    <ci-button @click="isLoading = !isLoading">Toggle Loading</ci-button>
  </div>
</template>
<script>
export default {
  data() {
    return {
      isLoading: false,
      selectedPeople: [],
      people: [],
    };
  },
  methods: {
    fetchPeople() {
      if (!this.people.length) {
        this.isLoading = true;
        setTimeout(() => {
          this.isLoading = false;
          this.people = [
            { value: 1, text: 'Robert Evans' },
            { value: 2, text: 'Tom Hendrich' },
            { value: 3, text: 'Tom Cook' },
            { value: 4, text: 'Anthony Johnson' },
            { value: 5, text: 'Jessica Landers' },
          ]
        }, 1000);
      }
    }
  }
}
</script>

No results text

Use the no-results-text prop to show text when no results match their input. This can help a user understand why the dropdown has disappeared.

Here we're also using the @input event to use the value of the input in our message.

<template>
  <ci-multi-select
    v-model="selectedPeople"
    :options="people"
    sublabel="People"
    :no-results-text="`'${inputVal}' is not a person in your orginazation.`"
    @input="inputVal = $event"
  />
</template>
<script>
export default {
  data() {
    return {
      inputVal: '',
      selectedPeople: [],
      people: [
        { value: 1, text: 'Robert Evans' },
        { value: 2, text: 'Tom Hendrich' },
        { value: 3, text: 'Tom Cook' },
        { value: 4, text: 'Anthony Johnson' },
        { value: 5, text: 'Jessica Landers' },
      ],
    };
  },
}
</script>

Error Handling

Use the error prop to set an error state and optional message. See the Form Field docs for more information about the error prop.

In this demo we we show no-results-text if the user searches for someone who doesn't exist, an error if the user attempts to select a user who doesn't exist, and a different error if they attempt to click submit with no selections.

<template>
  <div>
    <ci-multi-select
      v-model="selectedPeople"
      :options="people"
      sublabel="People"
      :no-results-text="`'${inputVal}' is not a person in your orginazation.`"
      :error="error"
      :success="success"
      required
      @input="inputVal = $event"
      @error="error = `You must choose someone from the provided list.`"
      @update="validateInput"
    />
    <br><br>
    <ci-button
      v-if="!success"
      @click="submitInput"
    >
      Submit
    </ci-button>
  </div>
</template>
<script>
export default {
  data() {
    return {
      error: false,
      success: false,
      inputVal: '',
      selectedPeople: [],
      people: [
        { value: 1, text: 'Robert Evans' },
        { value: 2, text: 'Tom Hendrich' },
        { value: 3, text: 'Tom Cook' },
        { value: 4, text: 'Anthony Johnson' },
        { value: 5, text: 'Jessica Landers' },
      ],
    };
  },
  methods: {
    validateInput() {
      this.error = this.selectedPeople.length
        ? false
        : 'You must select at least 1 person';
    },
    async submitInput() {
      this.validateInput();
      await this.$nextTick();
      if (!this.error) this.success = 'Your selection has been made';
    }
  }
}
</script>

Tag Variants

Use the tag-variant prop to pass a function that would determine the variant of selected option tags. By default tag variant is set to muted.

In this demo we set the tag variant to danger if the selected person is not currently available.

<template>
  <div>
    <ci-multi-select
      v-model="selectedPeople"
      :options="people"
      sublabel="People"
      :error="error"
      required
      :tag-variant="getTagVariant"
      @input="inputVal = $event"
      @update="validateInput"
    />
  </div>
</template>
<script>
export default {
  data() {
    return {
      error: false,
      inputVal: '',
      selectedPeople: [],
      people: [
        { value: 1, text: 'Robert Evans', isAvailable: true },
        { value: 2, text: 'Tom Hendrich', isAvailable: false },
        { value: 3, text: 'Tom Cook', isAvailable: false },
        { value: 4, text: 'Anthony Johnson', isAvailable: true },
        { value: 5, text: 'Jessica Landers', isAvailable: true },
      ],
    };
  },
  methods: {
    validateInput() {
      this.error = this.selectedPeople.some(u => !u.isAvailable)
        ? 'One or more people are currently unavailable.'
        : false;
    },
    getTagVariant (person) {
      return person.isAvailable ? 'muted' : 'danger';
    }
  }
}
</script>

Fully Customized Options

Using scoped slots, you can construct a fully customized options list with whatever data and layout you desire.

First, determine the structure of your data and tell the component what your value-key and text-key are. Then, pass your template into the option slot with slot-scope="props" and construct the layout you want. You can reach inside the props.option for the data based on your desired schema.

In this demo, we construct a dropdown of users with a name, avatar and job position. We use their name as the value of the input and the text to display in the dropdown when a user is selected. With a little bit of CSS we're able to get the layout we want as well.

<template>
  <ci-multi-select
    v-model="selectedPeople"
    sublabel="Assignee"
    placeholder="Choose a user"
    value-key="name"
    text-key="name"
    :options="people"
    fullwidth
  >
    <template slot="option" slot-scope="props">
      <div class="custom-option">
        <img class="custom-option__avatar" :src="props.option.avatar" :alt="props.option.name">
        <div class="custom-option__details">
          <div class="custom-option__name">{{ props.option.name }}</div>
          <div class="custom-option__position">{{ props.option.position }}</div>
        </div>
      </div>
    </template>
  </ci-multi-select>
</template>

<script>
export default {
  data() {
    return {
      selectedPeople: [],
      people: [
        { name: 'Robert Evans', avatar:'https://images.pexels.com/photos/736716/pexels-photo-736716.jpeg?auto=compress&cs=tinysrgb&crop=faces&fit=crop&h=200&w=200', position: 'Account Executive' },
        { name: 'Tom Hendrich', avatar:'https://api.uifaces.co/our-content/donated/fN82ubky.jpg', position: 'Account Executive II' },
        { name: 'Tom Cook', avatar:'https://images.pexels.com/photos/247917/pexels-photo-247917.jpeg?crop=faces&fit=crop&h=200&w=200&auto=compress&cs=tinysrgb', position: 'Technical Lead' },
        { name: 'Anthony Johnson', avatar:'https://randomuser.me/api/portraits/men/31.jpg', position: 'Security Manager' },
        { name: 'Jessica Landers', avatar:'https://images.unsplash.com/photo-1493666438817-866a91353ca9?ixlib=rb-0.3.5&q=80&fm=jpg&crop=faces&fit=crop&h=200&w=200&s=b616b2c5b373a80ffc9636ba24f7a4a9', position: 'Operations Manager' }
      ]
    };
  },
}
</script>
<style>
.custom-option {
  display: flex;
  align-items: center;
}

.custom-option__avatar {
  width: 40px;
  height: 40px;
  margin-right: 10px;
}
.custom-option__details {

}

.custom-option__name {
  font-weight: bold;
}

.custom-option__position {}
</style>

Allow Custom Values

Using the allow-custom-values prop you can allow the multi-select component to accept options that were not initially defined in the option prop. To display a custom message, like 'Add email address', set allow-custom-values to the value of your custom message. Use $$ in the allow-custom-values prop string to interpolate the input value in your custom message as shown in this demo.

<template>
  <ci-multi-select
    v-model="selectedTags"
    :options="options"
    :allow-custom-values="allowCustomValues"
    sublabel='tags'
    placeholder='Select an option'
  />
</template>
<script>
export default {
  data() {
    return {
      selectedTags: [],
      options: [
        { value: 1, text: 'Collective Results' },
        { value: 2, text: 'Front Line' },
        { value: 3, text: 'Operational Excellence' },
        { value: 4, text: 'Platformunification' },
        { value: 5, text: 'Product Lead' },
        { value: 6, text: 'Rock Star' },
        { value: 7, text: 'Team Player' },
        { value: 8, text: 'Walk With Purpose' },
        { value: 9, text: 'You Rock' },
      ],
      allowCustomValues: 'Add custom value $$ to list'
    };
  },
};
</script>

Custom Values & Validation

Couple validation with the allow-custom-values prop to only allow custom values when an input meets validation criteria.

In this demo, if the input is not in the select list and it is not a valid email address, we display a message using no-results-text, as soon as the input passes validation we remove the error state and update the allow-custom-values prop to allow the user to select their custom value. If the user attempts to enter an invalid email address, set an error state and display an error message.

<template>
  <ci-multi-select
    v-model="emails"
    :options="options"
    sublabel='Valid Emails'
    placeholder='Select an option'
    :allow-custom-values="allowCustomValues"
    :noResultsText="noResultsText"
    :error="error"
    @input="validateInput($event)"
    @update="error = false"
    @error="error = `Please provide a valid email address.`"
  />
</template>
<script>
export default {
  data() {
    return {
      emails: [],
      options: [
        { id: 1, text: 'test@test.com' },
        { id: 2, text: 'test2@test.com' },
      ],
      allowCustomValues: null,
      noResultsText: null,
      error: false,
      emailRegex: /^\w+@[a-zA-Z_]+?\.[a-zA-Z]{2,3}$/
    };
  },
  methods: {
    validateInput(inputVal) {
      if (this.emailRegex.test(inputVal)) {
        this.allowCustomValues = 'Add $$ to the list';
        this.noResultsText = null;
        this.error = false;
      } else if (inputVal !== '' && this.options.find((opt) => !opt.text.includes(inputVal))) {
        this.allowCustomValues = null;
        this.noResultsText = `${inputVal} is not a valid email address.`;
      }
    },
  },
};
</script>

Custom Filtering

Use the filter prop to define how the options get filtered when the multi-select's input is used. This can be useful when you want to the filter to look through more properties than just the text.

In this demo, we allow users to filter options by name and/or position.

<template>
  <ci-multi-select
    v-model="selectedPeople"
    sublabel="Assignee"
    placeholder="Select a user by name or position"
    :options="people"
    :filter="filterOptions"
    value-key="name"
    fullwidth
  >
    <template slot="option" slot-scope="props">
      <div class="custom-option">
        <img class="custom-option__avatar" :src="props.option.avatar" :alt="props.option.name">
        <div class="custom-option__details">
          <div class="custom-option__name">{{ props.option.name }}</div>
          <div class="custom-option__position">{{ props.option.position }}</div>
        </div>
      </div>
    </template>
  </ci-multi-select>
</template>

<script>
export default {
  data() {
    return {
      selectedPeople: [],
      people: [
        { name: 'Robert Evans', avatar:'https://images.pexels.com/photos/736716/pexels-photo-736716.jpeg?auto=compress&cs=tinysrgb&crop=faces&fit=crop&h=200&w=200', position: 'Account Executive' },
        { name: 'Tom Hendrich', avatar:'https://api.uifaces.co/our-content/donated/fN82ubky.jpg', position: 'Account Executive II' },
        { name: 'Tom Cook', avatar:'https://images.pexels.com/photos/247917/pexels-photo-247917.jpeg?crop=faces&fit=crop&h=200&w=200&auto=compress&cs=tinysrgb', position: 'Technical Lead' },
        { name: 'Anthony Johnson', avatar:'https://randomuser.me/api/portraits/men/31.jpg', position: 'Security Manager' },
        { name: 'Jessica Landers', avatar:'https://images.unsplash.com/photo-1493666438817-866a91353ca9?ixlib=rb-0.3.5&q=80&fm=jpg&crop=faces&fit=crop&h=200&w=200&s=b616b2c5b373a80ffc9636ba24f7a4a9', position: 'Operations Manager' }
      ],
    };
  },
  methods: {
    filterOptions(option, text) {
      return option.position.includes(text) || option.name.includes(text);
    },
  },
}
</script>
<style>
.custom-option {
  display: flex;
  align-items: center;
}

.custom-option__avatar {
  width: 40px;
  height: 40px;
  margin-right: 10px;
}
.custom-option__details {

}

.custom-option__name {
  font-weight: bold;
}

.custom-option__position {}
</style>

Events

The MultiSelect component emits various events you can use.

Event	Arguments	Description
@open	-	Emitted when the popover is opened
@input	The value inside the input	Emitted when the input field gets an input event
@error	The value inside the input	Emitted when enter is pressed and there are no matches found
@selectOption	The selected option object	Emitted when an option is selected
@selectAll	-	Emitted when select all is clicked
@unselect	The unselected option object	Emitted when an option is unselected by clicking the X in its tag
@update	The array of selected options	Whenever an option(s) is selected or unselected
@close	-	Emitted when the popover is closed