Select

The Select component provides a menu of options to the user.

Usage

Use the options prop to pass an array of options to your select. Use the placeholder prop to add a placeholder before any selectionis made. Use v-model for automatic data binding.

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

<template>
  <div>
    <ci-select
      v-model="mySelect"
      sublabel="Select"
      placeholder="Choose an option"
      :options="myOptions"
    />
    <br>
    <code>mySelect: {{mySelect}}</code>
  </div>
</template>

<script>
export default {
  data() {
    return {
      mySelect: '',
      myOptions: [
        { value: 1, text: 'Option text 1', pxClass: "Select,OptionCustomPX,OptionItem" },
        { value: 2, text: 'Option text 2' },
        { value: 3, text: 'Option text 3' },
        { value: 4, text: 'Option text 4' },
        { value: 5, text: 'Option text 5' },
        { value: 6, text: 'Option text 6' },
        { value: 7, text: 'Option text 7' },
        { value: 8, text: 'Option text 8' },
        { value: 9, text: 'Option text 9' },
        { value: 10, text: 'Option text 10' },
        { value: 11, text: 'Option text 11' },
        { value: 12, text: 'Option text 12' },
        { value: 13, text: 'Option text 13' },
        { value: 14, text: 'Option text 14' },
        { value: 15, text: 'Option text 15' }
      ]
    };
  },
}
</script>

Custom Options

Use the value-key prop to define the key for the value of your option. Use the text-key prop to define the key for the text to show when an option is selected. These props allow you to use data from an endpoint without needing to map it to a new format.

<template>
  <div>
    <ci-select
      v-model="mySelect"
      :options="myOptions"
      value-key="data"
      text-key="displayName"
    />
    <br>
    <code>mySelect: {{mySelect}}</code>
  </div>
</template>
<script>
export default {
  data() {
    return {
      mySelect: '',
      myOptions: [
        { data: 1, displayName: 'Option text ' },
        { data: 2, displayName: 'Option text 2' },
        { data: 3, displayName: 'Option text 3' },
        { data: 4, displayName: 'Option text 4' },
        { data: 5, displayName: 'Option text 5' }
      ]
    };
  },
}
</script>

Clearable

Use the clearable prop to allow user to clear value when same option is clicked

<template>
  <div>
    <ci-select
      v-model="mySelect"
      :options="myOptions"
      clearable
    />
    <br>
    <code>mySelect: {{mySelect}}</code>
  </div>
</template>
<script>
export default {
  data() {
    return {
      mySelect: '',
      myOptions: [
        { value: 1, text: 'Option text 1' },
        { value: 2, text: 'Option text 2' },
        { value: 3, text: 'Option text 3' },
        { value: 4, text: 'Option text 4' },
        { value: 5, text: 'Option text 5' },
      ]
    };
  },
}
</script>

Searchable option

Using searchable property you can allow user to filter list. It also enables user to input custom values and perform server-side search (see loading and allowCustomValues props)

Pass function in searchable prop to define how the options get filtered when the select's input is used. This can be useful when you want to the filter to look through more properties than just the text. If not passed - filtering will be performed against textKey

<template>
  <div>
    <ci-select
      v-model="mySelect"
      sublabel="Select"
      placeholder="Choose an option"
      :searchable="textAndIdFilter"
      :options="myOptions"
    />
    <br>
    <code>mySelect: {{mySelect}}</code>
  </div>
</template>

<script>
export default {
  data() {
    return {
      mySelect: null,
      myOptions: [
        { value: 1, text: 'Option text 1' },
        { value: 2, text: 'Option text 2' },
        { value: 3, text: 'Option text 3' },
        { value: 4, text: 'Option text 4' },
        { value: 5, text: 'Option text 5' },
        { value: 6, text: 'Option text 6' },
        { value: 7, text: 'Option text 7' },
        { value: 8, text: 'Option text 8' },
        { value: 9, text: 'Option text 9' },
        { value: 10, text: 'Option text 10' },
        { value: 11, text: 'Option text 11' },
        { value: 12, text: 'Option text 12' },
        { value: 13, text: 'Option text 13' },
        { value: 14, text: 'Option text 14' },
        { value: 15, text: 'Option text 15' }
      ]
    };
  },
  methods: {
    textAndIdFilter (option, text) {
      return option.value.toString().includes(text) || option.text.includes(text)
    }
  }
}
</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. Select dropdown will be prevented during loading

<template>
  <div>
    <ci-select
      v-model="mySelect"
      sublabel="Select"
      placeholder="Choose an option"
      searchable
      :loading="loading"
      :options="myOptions"
    />
    <br>
    <code>mySelect: {{mySelect}}</code>
    <div>
      <ci-button @click="loading = !loading">Toggle loader</ci-button>
    </div>
  </div>
</template>

<script>
export default {
  data() {
    return {
      mySelect: null,
      loading: false,
      myOptions: [
        { value: 1, text: 'Option text 1' },
        { value: 2, text: 'Option text 2' },
        { value: 3, text: 'Option text 3' }
      ]
    };
  }
}
</script>

Persist After Selection

Pass a boolean into the persistAfterSelection prop to close select list automatically once option is selected. By default it is set to false.

<template>
  <div>
    <ci-select
      v-model="mySelect"
      sublabel="Select"
      placeholder="Choose an option"
      searchable
      :persist-after-selection="false"
      :loading="loading"
      :options="myOptions"
    />
    <br>
    <code>mySelect: {{mySelect}}</code>
  </div>
</template>

<script>
export default {
  data() {
    return {
      mySelect: null,
      loading: false,
      myOptions: [
        { value: 1, text: 'Option text 1' },
        { value: 2, text: 'Option text 2' },
        { value: 3, text: 'Option text 3' }
      ]
    };
  }
}
</script>

Allow Custom Values

Using the allow-custom-values prop you can allow the select component accept option that were not initially defined in the options 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.

Additionally to value change, @addOption event will be emited if custom value is submitted. This functionality will not work for selects with options that are a simple array.

<template>
  <div>
    <ci-select
      v-model="mySelect"
      sublabel="Select"
      placeholder="Choose an option"
      allow-custom-values="Set new value '$$'"
      searchable
      :options="myOptions"
    />
    <br>
    <code>mySelect: {{mySelect}}</code>
  </div>
</template>

<script>
export default {
  data() {
    return {
      mySelect: null,
      myOptions: [
        { value: 1, text: 'Option text 1' },
        { value: 2, text: 'Option text 2' },
        { value: 3, text: 'Option text 3' }
      ]
    };
  }
}
</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-select
    v-model="mySelect"
    sublabel="Assignee"
    placeholder="Choose a user"
    value-key="name"
    text-key="name"
    :options="myOptions"
    :searchable="filterUser"
    allow-custom-values="$$"
    clearable
    @addOption="onOptionAdded"
  >
    <template slot="option" slot-scope="props">
      <div class="custom-option">
        <img v-if="props.option.avatar" 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-select>
</template>

<script>
export default {
  data() {
    return {
      mySelect: '',
      myOptions: [
        { 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: {
    filterUser (user, text) {
      const searchText = text.toLowerCase()
      return user.name.toLowerCase().includes(searchText) || user.position?.toLowerCase().includes(searchText)
    },
    onOptionAdded (option) {
      alert('Custom option ' + option.name + ' was added')
    }
  }
}
</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>

Infinite Scroll

The has-more-options prop can be used to indicate that not all available options are currently visible. When the user scrolls to the bottom of the options list, the load-more event will be emitted if the has-more-options prop is true.

Can be used together with loading prop to indicate that more options are being loaded, and with persist-during-loading prop to make sure that the options list stays open.

<template>
  <div>
    <ci-select
      v-model="mySelect"
      sublabel="Select"
      placeholder="Choose an option"
      :options="myOptions"
      :loading="isLoading"
      persist-during-loading
      :has-more-options="hasMoreOptions"
      @load-more="loadMore"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      mySelect: '',
      myOptions: [
        { value: 1, text: 'Option text 1', pxClass: "Select,OptionCustomPX,OptionItem" },
        { value: 2, text: 'Option text 2' },
        { value: 3, text: 'Option text 3' },
        { value: 4, text: 'Option text 4' },
        { value: 5, text: 'Option text 5' },
        { value: 6, text: 'Option text 6' },
        { value: 7, text: 'Option text 7' },
        { value: 8, text: 'Option text 8' },
        { value: 9, text: 'Option text 9' },
        { value: 10, text: 'Option text 10' },
        { value: 11, text: 'Option text 11' },
        { value: 12, text: 'Option text 12' },
        { value: 13, text: 'Option text 13' },
        { value: 14, text: 'Option text 14' }
      ],
      hasMoreOptions: true,
      isLoading: false
    };
  },
  methods: {
    loadMore() {
      this.isLoading = true

      setTimeout(() => {
        const lastOpt = this.myOptions.length
        this.myOptions.push(...[
          { value: lastOpt + 1, text: `Option text ${lastOpt + 1}` },
          { value: lastOpt + 2, text: `Option text ${lastOpt + 2}` }
        ])

        if (this.myOptions.length === 20) {
          this.hasMoreOptions = false
        }

        this.isLoading = false
      }, 500)
    }
  }
}
</script>

Auto-advance

When the auto-advance prop is set to true, on option select the cursor will auto-focus on the next input field.

This prop will not have an effect if persist-after-selection prop is set to true.

<template>
  <form>
    <ci-select
      v-model="mySelect"
      class="spacing"
      sublabel="Select"
      placeholder="Choose an option"
      :options="myOptions"
      auto-advance
    />
    <ci-input
      v-model="inputValue"
      sublabel="Enter text"
    />
  </form>
</template>

<script>
export default {
  data() {
    return {
      mySelect: '',
      inputValue: '',
      myOptions: [
        { value: 1, text: 'Option text 1' },
        { value: 2, text: 'Option text 2' },
        { value: 3, text: 'Option text 3' },
      ]
    };
  }
}
</script>
<style>
.spacing {
  margin-bottom: 20px;
}
</style>

Events

Event	Args	Emitted when...
@input	The selected option's object	An option is selected
@open	-	User opens the list
@close	-	List is closed
@search:input	Search input value	User types in search bar when searchable is enabled
@addOption	Custom option value	User submits custom value when allowCustomValues is enabled
@load-more	-	User scrolled to the bottom of the options list when has-more-options is true