# Select & Dropdown menus

# Select

# Introduction

The CpSelect component is a base text input component. Directly maps to a select element. It combines a label, select and validation message in one. Used for traditional forms.

It can also be:

  • required
  • disabled
<template>
  <cp-select v-model="selectedOption" :options="options" />
</template>

<script>
export default {
  data() {
    return {
      selectedOption: '',
      options: [
        {
          value: 'first_option',
          label: 'First option',
        },
        {
          value: 'second_option',
          label: 'Second option',
        },
        {
          value: 'third_option',
          label: 'Third option',
        },
      ],
    }
  },
}
</script>

# Values prop structure

The :options prop is an Array filled with Object formatted as follow, with 2 critical keys:

  • value: raw value
  • label: label displayed on the UI
const values = [
  {
    value: 'option_value',
    label: 'Option value',
  },
]

# Size

You can set the size of the CpSelect using font-size directly on the component

<cp-select label="12px font-sized select" style="font-size: 12px" :options="selectOptions" />
<cp-select label="14px font-sized select" style="font-size: 14px" :options="selectOptions" />
<cp-select label="16px font-sized select (default)" style="font-size: 16px" :options="selectOptions" />
<cp-select label="18px font-sized select" style="font-size: 18px" :options="selectOptions" />

# Large variation

You can have a specific large variation for the CpSelect using is-large property.

<cp-select is-large label="Large select" :options="selectOptions" />

# Label

You can add the label property to display it above the CpSelect.

<cp-select name="select" label="My wonderful select" :options="selectOptions" v-model="yourVariable" />  

# Disabled

<cp-select label="Disabled select" name="select" :options="selectOptions" v-model="yourVariable" disabled />

# Validation

You can either dynamically set input as errored with following props:

  • :is-invalid: display error visual styling
  • :error-message: display the error message
<cp-select
  name="select"
  :options="selectOptions"
  v-model="yourVariable"
  is-invalid
  error-message="Error message"
/>

# CpSelect Props

# :value [string, number]

The select value.

# :label string

The label used above the select element.

# :default-value string = 'Select an option'

CpSelect value when no option is selected yet.

# :options array

The options to show in the menu. [{ label: String, value: String | Number }]

# :name string

Native name mapped attribute for form purposes.

# :required bool = false

Makes the select element required.

# :readonly bool = false

Makes the select element readonly.

# :disabled bool = false

Makes the select element disabled.

# :is-invalid bool = false

Sets visual styling of an invalid select. Note that this does not effect any error-message.

# :error-message string

Sets select custom error message. Shown only when is-invalid = true.

# Select Menu

# Introduction

The CpSelectMenu component is an advanced interaction pattern which allows selection of an item from a dropdown list. It can be used as a substitute for the native CpSelect component.

The CpSelectMenu component works with an array of values passed through :values props, and a selectedValue object which works with v-model.

# Values prop structure

The :values prop is an Array filled with Object formatted as follow, with 2 critical keys:

  • value: raw value
  • label: label displayed on the UI
const values = [
  {
    value: 'option_value',
    label: 'option value',
  },
]

TIP

The v-model has also to follow this format (Object only).

# Close on select

The CpSelectMenu by default will be closed when an option is selected. This can be configured so that the menu closes on selection via :close-on-select props.

# Select Menu examples

# Single selected item

Selected value: { "label": "first value", "value": "first_value" }

<cp-select-menu
  v-model="{ value: 'first_value', label: 'first value' }"
  :values="[
    {
      value: 'first_value',
      label: 'first value',
    },
    {
      value: 'second_value',
      label: 'second value',
    },
    {
      value: 'third_value',
      label: 'third value',
    },
  ]"
  :selected-value="{ value: 'first_value', label: 'first value' }"
/>

# Add title and filter

  • :has-filter=true: to remove the search input filter.
  • @on-filter-change: event called on input changes.

Selected value: { "label": "first value", "value": "first_value" }

<cp-select-menu
  v-model="{ value: 'first_value', label: 'first value' }"
  :values="
    [
      {
        value: 'first_value',
        label: 'first value',
      },
      {
        value: 'second_value',
        label: 'second value',
      },
      {
        value: 'third_value',
        label: 'third value',
      },
    ].filter(menuValue => menuValue.label.toLowerCase().includes(selectMenuFilterValue.toLowerCase()))
  "
  :selected-value="{ value: 'first_value', label: 'first value' }"
  :has-filter="true"
  @on-filter-change="selectMenuFilterValue = arguments"
/>

# Custom dropdown title & filter input placeholder

  • :dropdown-title: dropdown title.
  • :dropdown-filter-placeholder: dropdown filter bar input placeholder.
<cp-select-menu
  :values="[{ value: 'first_value', label: 'first value' }, { value: 'second_value', label: 'second value' }]"
  :selected-value="{ value: 'first_value', label: 'first value' }"
  :has-filter="true"
  dropdown-title="Custom title"
  dropdown-filter-placeholder="Custom filter placeholder"
/>

# Empty view

It's possible to display a custom empty view instead of options list via :dropdown-empty-view-placeholder when there are no properties supplied. Note that empty view is also shown when options are being filtered and there are no search results.

<cp-select-menu
  :values="[]"
  :selected-value="{ value: 'first_value', label: 'first value' }"
  dropdown-empty-view-placeholder="Custom list placeholder"
/>

# CpSelectMenu Props

# :values array

The options to show in the menu. [{ label: String, value: String | Number }]

# :selected-value object

The selected value. { label: String, value: String | Number }

# :is-multiselect bool = false⚠️ Not usable for now

When true, multi select is accounted for.

# :has-filter bool = false

When true, show the dropdown filter bar.

The title of the dropdown.

The dropdown filter bar input placeholder.

Text that is displayed instead of the options list when there are no options.

# :close-on-select bool = true

If it's set to false, the dropdown will stay open when an option is selected.

# v-model or @input func = () => {}

Function that is called as the @change event when click on a list item. It works like a radio button.

# @filter-change func = () => {}

Function that is called as the @input event when the dropdown filter bar input value is updated.

# @on-close func = () => {}

Function that is called after the dropdown was closed.