vue-superselect

Appearance

Programmatic Control ​

Control the select component from external code. Open, close, toggle, clear, and focus the select from buttons, keyboard shortcuts, or any application logic.

Compound Component: Template Ref ​

Use a template ref on SelectRoot to access exposed methods. This is the simplest approach when using the compound component API.

API Setup (Template Ref Control) ​

vue
<script setup>
import { ref } from 'vue'
import { SelectRoot } from 'vue-superselect'

const selectRef = ref(null)
const selected = ref(null)

function clearAndFocus() {
  selectRef.value?.clear()
  selectRef.value?.focus()
}
</script>
Programmatic Control via Template Ref

Exposed Methods ​

SelectRoot exposes these methods via template ref:

MethodSignatureDescription
open()() => voidOpens the dropdown
close()() => voidCloses the dropdown
toggle()() => voidToggles the dropdown open/closed
clear()() => voidResets the value to null (single) or [] (multi)
focus()() => voidFocuses the input element
vue
<script setup>
import { ref } from 'vue'
import { SelectRoot } from 'vue-superselect'

const selectRef = ref(null)
const selected = ref(null)

function openAndFocus() {
  selectRef.value?.open()
  selectRef.value?.focus()
}
</script>

<template>
  <button @click="openAndFocus">Open Select</button>
  <button @click="selectRef?.clear()">Clear</button>

  <SelectRoot ref="selectRef" v-model="selected">
    <!-- ... -->
  </SelectRoot>
</template>

Options API uses the same pattern via this.$refs.selectRef?.open() / focus() / clear().

Composable API: Full Control ​

The useSelect composable returns the same control methods directly, plus reactive state you can read and write to. This gives you maximum flexibility for complex use cases.

Programmatic Control via Composable

Composable Methods and State ​

useSelect() returns control methods as plain functions, no template ref needed:

ts
const {
  // Control methods
  open,       // () => void
  close,      // () => void
  toggle,     // () => void
  clear,      // () => void
  focus,      // () => void
  dismiss,    // () => void

  // Reactive state (readable and writable)
  value,      // Ref<T | T[] | null>
  isOpen,     // Ref<boolean>
  query,      // Ref<string>

  // Read-only state
  visibleItems, // Ref<CollectionItem<T>[]>
  activeId,     // Ref<string | null>
  isAtMax,      // Ref<boolean>
  disabled,     // Ref<boolean>
} = useSelect({ items, labelKey: 'label', valueKey: 'id' })

Setting Value Programmatically ​

With the composable, you can set the value directly:

ts
// Select a specific item
value.value = 'some-id'

// Select random
const random = items[Math.floor(Math.random() * items.length)]
value.value = random.id

// Clear
clear()  // or: value.value = null

With the compound component API, use v-model reactivity:

ts
// The v-model ref controls the value
const selected = ref(null)

// Set programmatically
selected.value = 'some-id'

// Clear
selected.value = null

Common Patterns ​

Open on External Event ​

ts
// Open the select when a keyboard shortcut is pressed
function onKeyDown(event: KeyboardEvent) {
  if (event.key === 'k' && (event.metaKey || event.ctrlKey)) {
    event.preventDefault()
    selectRef.value?.open()
    selectRef.value?.focus()
  }
}

Reset on Form Submit ​

ts
function onSubmit() {
  // Process the selected value
  saveData(selected.value)

  // Reset the select
  selectRef.value?.clear()
}

Controlled Open State ​

If you need external control over open/closed state, use v-model:open.
Full controlled/uncontrolled patterns are covered in Controlled State.

Next Steps ​