AisCombobox

Comboboxes are the foundation of accessible autocompletes and command palettes for your app, complete with robust support for keyboard navigation.

Option specification

An array of strings or objects that define the selectable options for your Combobox.

String options

The first method to populate a Combobox is to bind the options prop to an array of strings.

John Smith

v-model: John Smith

<script setup>
  import { ref } from "vue"
  import AisCombobox from "@/components/combobox/AisCombobox.vue";

  const selectedValue = ref('John Smith')
  const options = ref([
    'David Drew',
    `Bo Jackson`,
    'John Smith',
    'Steve Reynolds',
    'Clark Thomas',
  ])
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedValue"
                 :options="options"
    ></AisCombobox>

    <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedValue }}</div>
  </div>
</template>

Object options

The options prop will also accept structured data in the form of an array of objects. By default, the component will use the following field keys to populate each option: label, value, and disabled.

Michael Jordan

v-model: 23

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedOption"
                 :options="options"
    ></AisCombobox>

      <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedOption }}</div>
  </div>

</template>

<script setup>
  import { ref } from "vue"
  import AisCombobox from "@/components/combobox/AisCombobox.vue";

  const options = ref([
    { value: 23, label: 'Michael Jordan', disabled: false },
    { value: 10, label: 'BJ Armstrong', disabled: false },
    { value: 33, label: 'Scottie Pippen', disabled: false },
    { value: 50, label: 'Michael Jackson', disabled: true },
    { value: 32, label: 'Magic Johnson', disabled: false },
  ])
  const selectedOption = ref(options.value[0].value)
</script>

Object Keys

If your objects don't have those default field keys, or you just want to use different field keys from your objects, you can use these props: labelKey, valueKey, and disabledKey.

Chancey Yepiskov

v-model: 71708376

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";

const options = ref([
  { "id": 7032,"hawkId": "cyepiskov0", "univId": "71708376", "firstName": "Chancey", "lastName": "Yepiskov", "fullName": "Chancey Yepiskov", "email": "chancey-yepiskov@uiowa.edu", "hireDate": "05/09/1990", "retired": false,"inactive": true },
  { "id": 2701,"hawkId": "beyden1", "univId": "75578382", "firstName": "Beaufort", "lastName": "Eyden", "fullName": "Beaufort Eyden", "email": "beaufort-eyden@uiowa.edu", "hireDate": "06/05/1998", "retired": false,"inactive": false },
  { "id": 9380,"hawkId": "fstokey2", "univId": "70294083", "firstName": "Franky", "lastName": "Stokey", "fullName": "Franky Stokey", "email": "franky-stokey@uiowa.edu", "hireDate": "06/11/1993", "retired": false,"inactive": true },
  { "id": 8167,"hawkId": "mloisi3", "univId": "71885795", "firstName": "Maximilien", "lastName": "Loisi", "fullName": "Maximilien Loisi", "email": "maximilien-loisi@uiowa.edu", "hireDate": "01/02/1996", "retired": false,"inactive": false },
  { "id": 3167,"hawkId": "ckunkler4", "univId": "73777687", "firstName": "Cyrillus", "lastName": "Kunkler", "fullName": "Cyrillus Kunkler", "email": "cyrillus-kunkler@uiowa.edu", "hireDate": "06/30/1990", "retired": false,"inactive": false },
  { "id": 7137,"hawkId": "nroggerone5", "univId": "75354999", "firstName": "Noella", "lastName": "Roggerone", "fullName": "Noella Roggerone", "email": "noella-roggerone@uiowa.edu", "hireDate": "03/08/1990", "retired": false,"inactive": true },
  { "id": 7477,"hawkId": "tmcnamara6", "univId": "73037787", "firstName": "Tannie", "lastName": "McNamara", "fullName": "Tannie McNamara", "email": "tannie-mcnamara@uiowa.edu", "hireDate": "12/26/2000", "retired": true,"inactive": true },
  { "id": 8112,"hawkId": "csneesby7", "univId": "73212220", "firstName": "Cherlyn", "lastName": "Sneesby", "fullName": "Cherlyn Sneesby", "email": "cherlyn-sneesby@uiowa.edu", "hireDate": "09/20/2020", "retired": false,"inactive": false },
  { "id": 5702,"hawkId": "lcouves8", "univId": "76168484", "firstName": "Linnell", "lastName": "Couves", "fullName": "Linnell Couves", "email": "linnell-couves@uiowa.edu", "hireDate": "05/28/1997", "retired": false,"inactive": true },
  { "id": 8338,"hawkId": "gtinniswood9", "univId": "72930577", "firstName": "Gerrard", "lastName": "Tinniswood", "fullName": "Gerrard Tinniswood", "email": "gerrard-tinniswood@uiowa.edu", "hireDate": "11/25/2020", "retired": true,"inactive": true },
])
const selectedOption = ref(options.value[0].univId)
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedOption"
                 :options="options"
                 value-key="univId"
                 label-key="fullName"
                 disabled-key="retired"
    ></AisCombobox>

    <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedOption }}</div>
  </div>

</template>

multiple

Use the multiple boolean prop to allow for selecting more than one option. You will also need to bind an array as your v-model instead of binding a string.

Durward Reynolds, Kenton Towne

v-model: [ 1, 2 ]

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";

const people = [
  { value: 1, label: 'Durward Reynolds' },
  { value: 2, label: 'Kenton Towne' },
  { value: 3, label: 'Therese Wunsch' },
  { value: 4, label: 'Benedict Kessler' },
  { value: 5, label: 'Katelyn Rohan' },
  { value: 6, label: 'David Drew' },
  { value: 7, label: `Bo Jackson` },
  { value: 8, label: 'John Smith' },
  { value: 9, label: 'Steve Reynolds' },
  { value: 10, label: 'Clark Thomas' },
]
const selectedPeople = ref([people[0].value, people[1].value])  // notice that this is an array
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedPeople"
                 :options="people"
                 multiple
    ></AisCombobox>

    <div class="grid gap-2">
      <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedPeople }}</div>
    </div>
  </div>
</template>

check-on-right

The checkmark icon that represents the selected option is displayed on the left side of the option by default. To display this checkmark on the right, use the check-on-right boolean prop. You can use check-on-right by itself or :check-on-right="true".

Michael Jordan

v-model: Michael Jordan

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";

const selectedValue = ref('Michael Jordan')
const options = ref([
  'Michael Jordan',
  `Magic Johnson`,
  'Michael Jackson',
  'Dwayne Johnson',
  'John Legend',
  'Reggie Jackson',
  'John Lennon',
])
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-start">
    <AisCombobox v-model="selectedValue"
                 :options="options"
                 check-on-right
    ></AisCombobox>

    <div class="grid gap-2">
      <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedValue }}</div>
    </div>
  </div>
</template>

display-value

This only applies when the options are objects. This prop accepts a function which returns the string to be displayed in the input for the selected option.

Franky Stokey (franky-stokey@uiowa.edu)

v-model: fstokey2

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";

const options = ref([
  { "id": 7032,"hawkId": "cyepiskov0", "univId": "71708376", "firstName": "Chancey", "lastName": "Yepiskov", "fullName": "Chancey Yepiskov", "email": "chancey-yepiskov@uiowa.edu", "hireDate": "05/09/1990", "retired": false,"inactive": true },
  { "id": 2701,"hawkId": "beyden1", "univId": "75578382", "firstName": "Beaufort", "lastName": "Eyden", "fullName": "Beaufort Eyden", "email": "beaufort-eyden@uiowa.edu", "hireDate": "06/05/1998", "retired": false,"inactive": false },
  { "id": 9380,"hawkId": "fstokey2", "univId": "70294083", "firstName": "Franky", "lastName": "Stokey", "fullName": "Franky Stokey", "email": "franky-stokey@uiowa.edu", "hireDate": "06/11/1993", "retired": false,"inactive": true },
  { "id": 8167,"hawkId": "mloisi3", "univId": "71885795", "firstName": "Maximilien", "lastName": "Loisi", "fullName": "Maximilien Loisi", "email": "maximilien-loisi@uiowa.edu", "hireDate": "01/02/1996", "retired": false,"inactive": false },
  { "id": 3167,"hawkId": "ckunkler4", "univId": "73777687", "firstName": "Cyrillus", "lastName": "Kunkler", "fullName": "Cyrillus Kunkler", "email": "cyrillus-kunkler@uiowa.edu", "hireDate": "06/30/1990", "retired": false,"inactive": false },
  { "id": 7137,"hawkId": "nroggerone5", "univId": "75354999", "firstName": "Noella", "lastName": "Roggerone", "fullName": "Noella Roggerone", "email": "noella-roggerone@uiowa.edu", "hireDate": "03/08/1990", "retired": false,"inactive": true },
  { "id": 7477,"hawkId": "tmcnamara6", "univId": "73037787", "firstName": "Tannie", "lastName": "McNamara", "fullName": "Tannie McNamara", "email": "tannie-mcnamara@uiowa.edu", "hireDate": "12/26/2000", "retired": true,"inactive": true },
  { "id": 8112,"hawkId": "csneesby7", "univId": "73212220", "firstName": "Cherlyn", "lastName": "Sneesby", "fullName": "Cherlyn Sneesby", "email": "cherlyn-sneesby@uiowa.edu", "hireDate": "09/20/2020", "retired": false,"inactive": false },
  { "id": 5702,"hawkId": "lcouves8", "univId": "76168484", "firstName": "Linnell", "lastName": "Couves", "fullName": "Linnell Couves", "email": "linnell-couves@uiowa.edu", "hireDate": "05/28/1997", "retired": false,"inactive": true },
  { "id": 8338,"hawkId": "gtinniswood9", "univId": "72930577", "firstName": "Gerrard", "lastName": "Tinniswood", "fullName": "Gerrard Tinniswood", "email": "gerrard-tinniswood@uiowa.edu", "hireDate": "11/25/2020", "retired": true,"inactive": true },
])
const selectedOption = ref(options.value[2].hawkId)
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedOption"
                 :options="options"
                 label-key="fullName"
                 value-key="hawkId"
                 :display-value="(person) => `${person.fullName} (${person.email})`"
    ></AisCombobox>

    <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedOption }}</div>
  </div>

</template>

size

The size prop takes the standard sm, md, and lg values and adjusts the size of the combobox accordingly.

Small

Medium

Large

Extra-large

Michael Jordan

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";
import AisRadioGroup from "@/components/radio-group/AisRadioGroup.vue";

const selectedValue = ref('Michael Jordan')
const options = ref([
  'Michael Jordan',
  `Magic Johnson`,
  'Michael Jackson',
  'Dwayne Johnson',
  'John Legend',
  'Reggie Jackson',
  'John Lennon',
])
const sizes = ref([
  { value: 'sm', label: 'Small' },
  { value: 'md', label: 'Medium' },
  { value: 'lg', label: 'Large' },
  { value: 'xl', label: 'Extra-large' },
])
const size = ref('md')
</script>

<template>
  <div class=" flex flex-col gap-4 w-1/2">
    <div>
      <AisRadioGroup v-model="size" :options="sizes" size="sm" buttons variant="secondary" class="rounded"/>
    </div>
    <div>
      <AisCombobox v-model="selectedValue"
                   :options="options"
                   :size="size"
      ></AisCombobox>
    </div>

  </div>
</template>

icon

AisCombobox accepts an icon prop to display an icon in the combobox. icon will accept either a FontAwesome icon definition or a string for one of our standard icons.

Michael Jordan

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";

const selectedValue = ref('Michael Jordan')
const options = ref([
  'Michael Jordan',
  `Magic Johnson`,
  'Michael Jackson',
  'Dwayne Johnson',
  'John Legend',
  'Reggie Jackson',
  'John Lennon',
])
</script>

<template>
  <div class="w-1/2">
    <AisCombobox v-model="selectedValue"
                 :options="options"
                 icon="user"
    ></AisCombobox>
  </div>
</template>

selected-icon

AisCombobox accepts a selected-icon prop to override the default icon used to identify the selected combobox option. selected-icon will accept either a FontAwesome icon definition or a string for one of our standard icons.

John Smith

v-model: John Smith

<script setup>
  import { ref } from "vue"
  import AisCombobox from "@/components/combobox/AisCombobox.vue";
  import { faCircleCheck } from '@fortawesome/free-solid-svg-icons'
  import { library } from '@fortawesome/fontawesome-svg-core'
  library.add( faCircleCheck )

  const selectedValue = ref('John Smith')
  const options = ref([
    'David Drew',
    `Bo Jackson`,
    'John Smith',
    'Steve Reynolds',
    'Clark Thomas',
  ])
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedValue"
                 :options="options"
                 :selected-icon="faCircleCheck"
    ></AisCombobox>

    <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedValue }}</div>
  </div>
</template>

class

AisCombobox accepts a selected-icon-class prop to customize the selected icon

John Smith

v-model: John Smith

<script setup>
  import { ref } from "vue"
  import AisCombobox from "@/components/combobox/AisCombobox.vue";

  const selectedValue = ref('John Smith')
  const options = ref([
    'David Drew',
    `Bo Jackson`,
    'John Smith',
    'Steve Reynolds',
    'Clark Thomas',
  ])
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedValue"
                 :options="options"
                 check-on-right
                 selected-icon-class="mx-auto flex items-center justify-center h-6 w-6 rounded-full text-sm bg-secondary text-primary border border-primary"
    ></AisCombobox>

    <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedValue }}</div>
  </div>
</template>

slot

AisCombobox offers a selected-icon slot to override the default icon used to identify the selected combobox option.

BJ Armstrong

v-model: 10

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedOption"
                 :options="options"
    >
      <template #selectedIcon>
        <img src="/tigerhawk.png" class="w-6"/>
      </template>
    </AisCombobox>

      <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedOption }}</div>
  </div>

</template>

<script setup>
  import { ref } from "vue"
  import AisCombobox from "@/components/combobox/AisCombobox.vue";

  const options = ref([
    { value: 23, label: 'Michael Jordan', disabled: false },
    { value: 10, label: 'BJ Armstrong', disabled: false },
    { value: 33, label: 'Scottie Pippen', disabled: false },
    { value: 50, label: 'Michael Jackson', disabled: true },
    { value: 32, label: 'Magic Johnson', disabled: false },
  ])
  const selectedOption = ref(options.value[1].value)
</script>

disabled

Use the boolean disabled prop to disable an AisCombobox. You can use disabled by itself or :disabled="true". A combobox within a disabled AisForm or AisField will automatically be set to disabled.

Michael Jordan

Combobox Field

Michael Jordan

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";
import AisField from "@/components/field/AisField.vue";

const selectedValue = ref('Michael Jordan')
const options = ref([
  'Michael Jordan',
  `Magic Johnson`,
  'Larry Bird',
])
</script>

<template>
  <div class="grid gap-8">
    <div class="w-1/2">
      <AisCombobox
        v-model="selectedValue"
        :options="options"
        disabled
      />
    </div>
    <AisField
      disabled
      label="Combobox Field" class="w-1/2"
    >
      <AisCombobox
        v-model="selectedValue"
        :options="options"
      />
    </AisField>
  </div>
</template>

invalid

Use the boolean prop invalid to mark an AisCombobox as invalid. You can use invalid by itself or :invalid="true". A combobox inside an AisField with errors will automatically be set to invalid.

Michael Jordan

Combobox Field

Larry Bird

• This field has an error

<script setup>
import { ref } from "vue"
import AisField from "@/components/field/AisField.vue";
import AisCombobox from "@/components/combobox/AisCombobox.vue";

const selection1 = ref('Michael Jordan')
const selection2 = ref('Larry Bird')
const options = ref([
  'Michael Jordan',
  `Magic Johnson`,
  'Larry Bird',
])
</script>

<template>
  <div class="grid gap-8">
    <div class="w-1/2">
      <AisCombobox
        invalid
        v-model="selection1"
        :options="options"
      />
    </div>
    <AisField
      label="Combobox Field"
      errors="This field has an error" class="w-1/2" >
      <AisCombobox
        v-model="selection2"
        :options="options"
      />
    </AisField>
  </div>
</template>

status

AisCombobox accepts a status prop to place the input in a logical state. status will accept the values: busy, success, error, and required. The current state will be expressed through an icon on the right side of the input.

Developers are responsible for maintaining a field's status as a user works through a particular process flow.

Busy

Success

Error

Required

Michael Jordan

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";
import AisRadioGroup from "@/components/radio-group/AisRadioGroup.vue";

const selectedValue = ref('Michael Jordan')
const options = ref([
  'Michael Jordan',
  `Magic Johnson`,
  'Michael Jackson',
  'Dwayne Johnson',
  'John Legend',
  'Reggie Jackson',
  'John Lennon',
])
const statuses = ref([
  { value: 'busy', label: 'Busy' },
  { value: 'success', label: 'Success' },
  { value: 'error', label: 'Error' },
  { value: 'required', label: 'Required' },
])
const status = ref('busy')
</script>

<template>
  <div class="grid gap-8 w-1/2">
    <div>
      <AisRadioGroup v-model="status" :options="statuses" size="sm" buttons variant="secondary" outline class="rounded"/>
    </div>
    <div>
      <AisCombobox v-model="selectedValue"
                   :options="options"
                   :status="status"
      ></AisCombobox>
    </div>
  </div>
</template>

Rounded

Add one of the Tailwind rounded classes to the class attribute of the AisCombobox.

none

rounded-sm

rounded

rounded-md

rounded-lg

rounded-xl

rounded-2xl

rounded-3xl

rounded-full

Michael Jordan

<script setup>
import { ref } from "vue"
import AisCombobox from "@/components/combobox/AisCombobox.vue";
import AisRadioGroup from "@/components/radio-group/AisRadioGroup.vue";

const selectedValue = ref('Michael Jordan')
const options = ref([
  'Michael Jordan',
  `Magic Johnson`,
  'Michael Jackson',
  'Dwayne Johnson',
  'John Legend',
  'Reggie Jackson',
  'John Lennon',
])

const roundedOptions = ref([
  { value: 'none', label: 'none' },
  { value: 'sm', label: 'rounded-sm' },
  { value: 'rounded', label: 'rounded' },
  { value: 'md', label: 'rounded-md' },
  { value: 'lg', label: 'rounded-lg' },
  { value: 'xl', label: 'rounded-xl' },
  { value: '2xl', label: 'rounded-2xl' },
  { value: '3xl', label: 'rounded-3xl' },
  { value: 'full', label: 'rounded-full' },
])
const rounded = ref('rounded')
</script>

<template>
  <div class="grid gap-8">
    <div>
      <AisRadioGroup
          v-model="rounded"
          :options="roundedOptions"
          name="radios"
          size="sm"
          buttons rounded outline
          variant="secondary"
      />
    </div>
    <div class="w-1/2">
      <AisCombobox v-model="selectedValue"
                   :options="options"
                   :rounded="rounded"
      ></AisCombobox>
    </div>
  </div>
</template>

Create

If you want to allow your users to enter a value that isn't already in the options list, then use the create prop. The create prop accepts an asynchronous function. This async function will:

• be called when the "Create" submit button is clicked on the "Add new Option" screen
• receive the new option object as the first and only parameter
• need to make an async call to your backend to add the option to your database
• need to refresh the combobox options

Additional props to customize the built-in create feature:

• create-label: this string will be appended to "Add " and will be displayed in the combo footer and as the title of the create panel
• create-opt-value-label: this string will be the label for the field of the new option value
• create-opt-descr-label: this string will be the label for the field of the new option description/label

Checking Account

v-model: 1234560

<script setup>
  import { ref } from "vue"
  import AisCombobox from "@/components/combobox/AisCombobox.vue";

  const options = ref([
    { value: 1234560, label: 'Checking Account' },
    { value: 1234561, label: 'Savings Account' },
    { value: 1234562, label: 'Retirement Account' },
    { value: 1234563, label: 'Vacation Account' },
    { value: 1234564, label: 'Emergency Account' },
  ])
  const selectedOption = ref(options.value[0].value)

  const addOption = async (opt) => await new Promise(r => setTimeout(r, 1000))
  // const addOption = async (opt) => await useAisFetch('/some/path', { method: 'POST', body: { option: opt } })
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedOption"
                 :options="options"
                 :create="addOption"
                 create-label="Account"
                 create-opt-value-label="Account Number"
                 create-opt-descr-label="Account Name"
    ></AisCombobox>

    <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedOption }}</div>
  </div>
</template>

Action Slot

If you want to add your own custom action screen within the combobox, use the action slot combined with the footer slot. Add something to the footer for the user to click to show your action screen using the slot prop showActionSlot. Add your custom screen in the action slot and use the slot prop hideActionSlot to easily hide the action screen and return to the combobox options screen.

R2-D2

v-model: r2d2

<script setup>
  import { ref } from "vue"
  import AisCombobox from "@/components/combobox/AisCombobox.vue";
  import AisButton from "@/components/button/AisButton.vue";
  import AisIconButton from "@/components/icon-button/AisIconButton.vue";

  const options = ref([
    { hawkId: 'r2d2', univId: '79599133', name: 'R2-D2', email: 'r2-d2@uiowa.edu' },
    { hawkId: 'c3po', univId: '70372677', name: 'C-3PO', email: 'c-3po@uiowa.edu' },
    { hawkId: 'bhans', univId: '73243814', name: 'Han Solo', email: 'han-solo@uiowa.edu' },
    { hawkId: 'skywalker', univId: '76949520', name: 'Luke Skywalker', email: 'luke-skywalker@uiowa.edu' },
  ])
  const selectedOption = ref(options.value[0].hawkId)
</script>

<template>
  <div class="grid grid-cols-2 gap-10 items-end">
    <AisCombobox v-model="selectedOption"
                 :options="options"
                 value-key="hawkId"
                 label-key="name"
    >
      <template #footer="{ showActionSlot }">
        <div class="combo-footer-item" @click="showActionSlot">Show Action Slot</div>
      </template>

      <template #action="{ hideActionSlot }">
        <div class="grid gap-0.5">

          <!-- Action Header -->
          <div class="p-2 border-b border-ui-gray-100 flex gap-2 basis-0 items-center">
            <div class="flex-1">
              <AisIconButton icon="arrow"
                             label="Back to Combobox Options"
                             class="rotate-180 hover:opacity-60"
                             @click="hideActionSlot"
              />
            </div>

            <div class="font-bold text-lg">Custom Action Slot</div>

            <div class="flex-1"></div>
          </div>

          <!-- Action Body -->
          <div class="grid gap-4 p-2 text-center font-bold text-xl">
            <div class="p-4">Some</div>
            <div class="p-4">Custom</div>
            <div class="p-4">Content</div>
            <div class="p-4">Here</div>
          </div>

          <!-- Action Footer -->
          <div class="p-2 border-t border-ui-gray-100 flex gap-4 justify-between">
            <AisButton outline rounded hover fast press
                       variant="default"
                       icon="cancel"
                       size="sm"
                       @click="hideActionSlot">Cancel</AisButton>
          </div>

        </div>
      </template>
    </AisCombobox>

    <div class="p-2 bg-ui-gray-50 border rounded">v-model: {{ selectedOption }}</div>
  </div>
</template>

Events

@update:modelValue

AisCombobox uses Vue 3's standard v-model configuration. As a result, you can bind the @update:modelValue to do additional work when the selection changes. It will be fired every time v-model changes.

@load

The @load event fires when the combobox is loaded. The event's payload contains the selected value from the options array. If options is an array of objects, the payload will be the selected object and not the primitive value emitted by v-model.

@load may be used to capture the selected object or to trigger additional initialization logic. See the code example for @change to see how the two events work together.

@change

The @change event fires when the user selects a new value. The event's payload contains the selected value from the options array. If options is an array of objects, the payload will be the selected object and not the primitive value emitted by v-model. This is what makes @change different from @update:modelValue.

@change may be used to capture the selected object or to trigger additional work. When capturing the selected object, use @load to initialize the selection. Notice how both v-model and selectedObject have a value on page load in the example below.

Chancey Yepiskov

v-model:

71708376

selectedObject:

{}

<script setup>
  import { ref } from "vue";
  import { AisCombobox } from "@ais-public/ais-components";

  const options = ref([
    { "id": 7032,"hawkId": "cyepiskov0", "univId": "71708376", "firstName": "Chancey", "lastName": "Yepiskov", "fullName": "Chancey Yepiskov", "email": "chancey-yepiskov@uiowa.edu", "hireDate": "05/09/1990", "retired": false,"inactive": true },
    { "id": 2701,"hawkId": "beyden1", "univId": "75578382", "firstName": "Beaufort", "lastName": "Eyden", "fullName": "Beaufort Eyden", "email": "beaufort-eyden@uiowa.edu", "hireDate": "06/05/1998", "retired": false,"inactive": false },
    { "id": 9380,"hawkId": "fstokey2", "univId": "70294083", "firstName": "Franky", "lastName": "Stokey", "fullName": "Franky Stokey", "email": "franky-stokey@uiowa.edu", "hireDate": "06/11/1993", "retired": false,"inactive": true },
    { "id": 8167,"hawkId": "mloisi3", "univId": "71885795", "firstName": "Maximilien", "lastName": "Loisi", "fullName": "Maximilien Loisi", "email": "maximilien-loisi@uiowa.edu", "hireDate": "01/02/1996", "retired": false,"inactive": false },
    { "id": 3167,"hawkId": "ckunkler4", "univId": "73777687", "firstName": "Cyrillus", "lastName": "Kunkler", "fullName": "Cyrillus Kunkler", "email": "cyrillus-kunkler@uiowa.edu", "hireDate": "06/30/1990", "retired": false,"inactive": false },
    { "id": 7137,"hawkId": "nroggerone5", "univId": "75354999", "firstName": "Noella", "lastName": "Roggerone", "fullName": "Noella Roggerone", "email": "noella-roggerone@uiowa.edu", "hireDate": "03/08/1990", "retired": false,"inactive": true },
    { "id": 7477,"hawkId": "tmcnamara6", "univId": "73037787", "firstName": "Tannie", "lastName": "McNamara", "fullName": "Tannie McNamara", "email": "tannie-mcnamara@uiowa.edu", "hireDate": "12/26/2000", "retired": true,"inactive": true },
    { "id": 8112,"hawkId": "csneesby7", "univId": "73212220", "firstName": "Cherlyn", "lastName": "Sneesby", "fullName": "Cherlyn Sneesby", "email": "cherlyn-sneesby@uiowa.edu", "hireDate": "09/20/2020", "retired": false,"inactive": false },
    { "id": 5702,"hawkId": "lcouves8", "univId": "76168484", "firstName": "Linnell", "lastName": "Couves", "fullName": "Linnell Couves", "email": "linnell-couves@uiowa.edu", "hireDate": "05/28/1997", "retired": false,"inactive": true },
    { "id": 8338,"hawkId": "gtinniswood9", "univId": "72930577", "firstName": "Gerrard", "lastName": "Tinniswood", "fullName": "Gerrard Tinniswood", "email": "gerrard-tinniswood@uiowa.edu", "hireDate": "11/25/2020", "retired": true,"inactive": true },
  ])
  const selectedOption = ref(options.value[0].univId)
  const selectedObject = ref({})

  const handleLoad = (value) => {
    console.log('Combobox load:', value)
    selectedObject.value = value
  }

  const handleChange = (value) => {
    console.log('Combobox change:', value)
    selectedObject.value = value
  }
</script>

<template>
  <div class="flex flex-col gap-4">
    <div class="w-1/2">
      <AisCombobox v-model="selectedOption"
                   :options="options"
                   valueKey="univId"
                   labelKey="fullName"
                   @load="handleLoad"
                   @change="handleChange"
      ></AisCombobox>
    </div>

    <div class="grid gap-4 p-4 bg-ui-gray-50 border rounded">
      <div class="flex gap-4 items-start justify-start">
        <div class="flex-none w-28 font-medium">v-model:</div>
        <div class="grow">{{ selectedOption }}</div>
      </div>
      <div class="flex gap-4 items-start justify-start">
        <div class="flex-none w-28 font-medium">selectedObject:</div>
        <div class="grow">{{ selectedObject }}</div>
      </div>
    </div>
  </div>
</template>

Component Reference

Props

Property	Type(s)	Required	Default	Description	Deprecated
checkOnRight	Boolean		false	When true, the checkmark(s) indicating selection will be on the right instead of the left	false
create	Func			The asynchronous Function to be called when the Create button is clicked. This is the function where you can add your logic for adding the new option to your backend/db/store/etc. Note: Function must be async	false
createLabel	String		'new option'	Label to be displayed in the create button in the combobox footer, and as the title of the create option panel	false
createOptDescrLabel	String		'New Option Description/Label'	Label to be displayed on the new option description field.	false
createOptValueLabel	String		'New Option Value'	Label to be displayed on the new option value field.	false
disabled	Boolean		false	Places component in a disabled state, when true	false
disabledKey	String		'disabled'	The property in the option object that will be used to determine whether the component is disabled	false
displayValue	Func		undefined	Customize the display text for the selected options	false
icon	Undefined		undefined	Optional icon to be displayed immediately prior to the text in the combobox default/collapsed view. Accepts either an object imported from the FontAwesome icon packs or a string specifying one of the preloaded, core icons	false
invalid	Boolean		false	Places component in a invalid state, when true	false
labelKey	String		'label'	The property in the option object that the user will see as the option label	false
menuHeight	Array, String		'max-h-[400px]'	Classes to set the height of the menu/options container	false
menuWidth	Array, String		'w-96'	Classes to set the width of the menu/options container.	false
modelValue	Array, Number, String		''	The selected value(s). If multiple, return value is Array; otherwise, String	false
multiple	Boolean		false	When true, multiple selections are allowed. Note: v-model must be an Array	false
options	Array		[]	The combobox options	false
placeholder	String		''	Placeholder text for combobox	false
rounded	Boolean, String		undefined	Applies rounded corners using TailwindCSS's rounded classes	false
selectedIcon	Undefined		undefined	The icon that designates the selected option. Accepts either an object imported from the FontAwesome icon packs or a string specifying one of the preloaded, core icons	false
selectedIconClass	Array, String		''	Classes to set to the selectedIcon.	false
size	String		undefined	Set the size of the component's appearance Valid values: xs, sm, md, lg, xl	false
status	String		undefined	Optional icon on the right side of the header to indicate the logical state of the card Valid values: busy, success, error, required	false
valueKey	String		'value'	The property in the option object that the user will see as the option value	false

Slots

Name	Scoped	Description
action		Slot for customizing the combobox action screen
footer		Slot for customizing the combobox menu footer
selectedIcon	No	Slot for customizing the icon used to designate the selected option

Events

Event	Arguments	Description
change	selectedOptions object - The selected option object(s)	Emitted when the selected values change
load	selectedOptions object - The selected option object(s)	Emitted when the combobox first loads, returning the initial selected option Object(s)
update:modelValue	modelValue union - The selected value(s)	Emitted when the selected values change