AisSelect

The AisSelect component produces a branded html <select> element. It is built on top of BaseSelect and intended to be used alongside other AIS form elements.

Option specification

Select options may be specified as an array (via the options prop), defined explicitly in the tag body, or both. This interface allows you to mix static and dynamic options.

String options

The first method to populate a select is to bind the options prop to an array of strings. Alternatively, AisSelect also accepts an array of numbers or booleans.

Option #1Option #2Option #3

v-model: Option #2

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

  const options = [
    'Option #1', 'Option #2', 'Option #3'
  ]

  const selectedOption = ref('Option #2')
</script>

<template>
  <div class="grid gap-8">
    <AisSelect
      :options="options"
      v-model="selectedOption"
    />

    <div class="p-4 bg-ui-gray-50 border rounded">
      v-model: {{selectedOption}}
    </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. You can use more appropriate fields in your object using the props: labelKey, valueKey, and disabledKey.

Option #1Option #2Option #3

v-model: 3

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

  const options = [
    { value: 1, label: 'Option #1', disabled: false},
    { value: 2, label: 'Option #2', disabled: false},
    { value: 3, label: 'Option #3', disabled: false},
  ]

  const selectedOption = ref(3)
</script>

<template>
  <div class="grid gap-8">
    <AisSelect
      :options="options"
      v-model="selectedOption"
    />

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

Default option

Use the defaultOption prop to specify an undefined or empty initial option when there is no default selection. defaultOption will accept either an object (matching the objects passed to options) or a string. When a string is passed the value of the default option will be undefined.

Select option...Option #1Option #2Option #3

v-model:

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

  const userPromptOption = {
    value: undefined, label: 'Select option...', disabled: false
  }

  const options = [
    { value: 1, label: 'Option #1', disabled: false},
    { value: 2, label: 'Option #2', disabled: false},
    { value: 3, label: 'Option #3', disabled: false},
  ]

  const selectedOption = ref(undefined)
</script>

<template>
  <div class="grid gap-8">
    <AisSelect
        :defaultOption="userPromptOption"
        :options="options"
        v-model="selectedOption"
    />

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

Default slot

In some cases, it may be useful to define options manually in markup. This can be done by defining traditional options in the body of AisSelect. In most cases, using the options prop is the preferred strategy.

Note, there are a couple of facts to keep in mind here. First, if options and the default slot are used together, the data specified by options comes first.

Secondly, explicit options require you to manually handle the selected attribute. You would need to use a test like: :selected="selectedOption === 'optionValue'" to initialize a selected value. (Otherwise we need to create an AisOption component to handle this case.)

Option #1Option #2Option #3

v-model:

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

  const selectedOption = ref(undefined)
</script>

<template>
  <div class="grid gap-8">
    <AisSelect v-model="selectedOption">
      <option value="1">Option #1</option>
      <option value="2">Option #2</option>
      <option value="3">Option #3</option>
    </AisSelect>

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

Head slot

AisSelect has a second slot named head. This allows you to explicitly define options that will appear between the defaultOption and options. The same caveats apply to options defined in the default slot.

Default option...Head #1Head #2Option #1Option #2Option #3

v-model:

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

const defaultOption = {value: undefined, label: 'Default option...', disabled: false }

const options = [
  { value: 1, label: 'Option #1', disabled: false},
  { value: 2, label: 'Option #2', disabled: false},
  { value: 3, label: 'Option #3', disabled: false},
]

const selectedOption = ref(undefined)
</script>

<template>
  <div class="grid gap-8">
    <AisSelect
        :defaultOption="defaultOption"
        :options="options"
        v-model="selectedOption"
    >
      <template #head>
        <option value="4">Head #1</option>
        <option value="5">Head #2</option>
      </template>
    </AisSelect>

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

Select Props

v-model

As illustrated in all the examples above, use the v-model directive to capture the value of the selected option. The selection is the simple value set on the option's value attribute. It may be a string, number, or boolean. It is not the object passed through the options array. You may get the selected object using the @load and @change events.

size

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

smmdlgxl

Option #1Option #2Option #3

<template>
  <div class="grid gap-8">
    <AisSelect :options="['sm', 'md', 'lg', 'xl']" v-model="selectedSize" />

    <AisSelect
        :size="selectedSize"
        :options="options"
        :modelValue="selectedOption"
    />
  </div>
</template>

<script setup>
  import {ref} from 'vue'
  import { AisSelect } from '@ais-public/ais-components'

  const options = [ 'Option #1', 'Option #2', 'Option #3']
  const selectedSize = ref('md')
  const selectedOption = ref('Option #2')
</script>

icon

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

Option #1Option #2Option #3

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

const options = [
  'Option #1', 'Option #2', 'Option #3'
]
const selectedOption = ref('Option #1')
</script>

<template>
  <div class="grid gap-8">
    <AisSelect
        icon="person"
        :options="options"
        v-model="selectedOption"
    />
  </div>
</template>

status

AisSelect 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.

busysuccesserrorrequired

<script setup>
  import { ref } from 'vue';
  import { AisSelect } from '@ais-public/ais-components'
  import { controlStates } from "@ais-public/ais-components/util/controls";

  const selectedStatus = ref('busy')
</script>

<template>
  <div class="grid gap-8">
    <AisSelect
      v-model="selectedStatus"
      :options="controlStates"
      :status="selectedStatus"
    />
  </div>
</template>

disabled

Use the boolean disabled prop to disable an AisSelect. See AisField's disabled prop for an alternative that may be more appropriate in the context of a form.

Option #1Option #2Option #3

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

const options = [
  'Option #1', 'Option #2', 'Option #3'
]
const selectedOption = ref('Option #1')

</script>

<template>
  <div class="grid gap-8">
    <AisSelect
        :options="options"
        v-model="selectedOption"
        disabled
    />
  </div>
</template>

invalid

Use the boolean invalid prop to mark an AisSelect as invalid. You can use invalid by itself or :invalid="true".

Option #1Option #2Option #3

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

const options = [
  'Option #1', 'Option #2', 'Option #3'
]
const selectedOption = ref('Option #1')

</script>

<template>
  <div class="grid gap-8">
    <AisSelect
        :options="options"
        v-model="selectedOption"
        invalid
    />
  </div>
</template>

Events

@update:modelValue

AisSelect 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 select 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.

Option #1Option #2Option #3

v-model: 1

selectedObject:

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

const options = [
  {value: 1, label: 'Option #1', disabled: false},
  {value: 2, label: 'Option #2', disabled: false},
  {value: 3, label: 'Option #3', disabled: false},
]

const selectedOption = ref(1)
let selectedObject = ref(undefined)

const initializeSelection = function (value) {
  console.log('AisSelect loaded', value)
  selectedObject.value = value
}

const handleChange = function (value) {
  console.log('AisSelect changed', value)
  selectedObject.value = value
}

const handleFocus = function (value) {
  console.log('AisSelect focus', value)
}

const handleBlur = function (value) {
  console.log('AisSelect blur', value)
}
</script>

<template>
  <div className="grid gap-8">
    <AisSelect
        :options="options"
        v-model="selectedOption"
        @load="initializeSelection"
        @change.capture="handleChange"
        @focus="handleFocus"
        @blur="handleBlur"
    />

    <div className="grid gap-2 p-4 bg-ui-gray-50 border rounded">
      <div>v-model: {{ selectedOption }}</div>
      <div>selectedObject: {{ selectedObject }}</div>
    </div>
  </div>
</template>