or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ajax-loading.mdcustomization.mdindex.mdkeyboard-navigation.mdsearch-filtering.mdselection.mdtagging.md
tile.json

tessl/npm-vue-select

Everything you wish the HTML select element could do, wrapped up into a lightweight, extensible Vue component.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vue-select@3.20.x

To install, run

npx @tessl/cli install tessl/npm-vue-select@3.20.0

index.mddocs/

Vue Select

Vue Select is a comprehensive Vue.js component that enhances the standard HTML select element with advanced functionality including filtering, searching, tagging, AJAX support, and accessibility features. It provides a lightweight (~20kb total), zero-dependency solution for creating sophisticated dropdown interfaces with support for single and multiple selections, custom styling through slots and SCSS variables, server-side rendering (SSR), and extensive customization options.

Package Information

  • Package Name: vue-select
  • Package Type: npm
  • Language: JavaScript/Vue.js
  • Installation: npm install vue-select

Core Imports

import vSelect from "vue-select";

Named imports:

import { VueSelect, mixins } from "vue-select";

CSS import (required):

import "vue-select/dist/vue-select.css";

For Vue 2 global registration:

import Vue from "vue";
import vSelect from "vue-select";

Vue.component("v-select", vSelect);

Basic Usage

<template>
  <div>
    <!-- Single selection -->
    <v-select 
      v-model="selected"
      :options="options"
      placeholder="Choose an option..."
    />
    
    <!-- Multiple selection -->
    <v-select
      v-model="multipleSelected"
      :options="options"
      multiple
      placeholder="Choose multiple options..."
    />
    
    <!-- Searchable with custom labels -->
    <v-select
      v-model="userSelected"
      :options="users"
      label="name"
      :reduce="user => user.id"
      placeholder="Search users..."
    />
  </div>
</template>

<script>
import vSelect from "vue-select";

export default {
  components: { vSelect },
  data() {
    return {
      selected: null,
      multipleSelected: [],
      userSelected: null,
      options: ["Option 1", "Option 2", "Option 3"],
      users: [
        { id: 1, name: "John Doe", email: "john@example.com" },
        { id: 2, name: "Jane Smith", email: "jane@example.com" }
      ]
    };
  }
};
</script>

Architecture

Vue Select is built around several key architectural components:

  • Core Component: Single Vue component (Select.vue) with extensive prop-based configuration
  • Mixin System: Modular functionality through Vue mixins (ajax, typeAheadPointer, pointerScroll)
  • Slot System: Comprehensive slot-based customization for all UI elements
  • Event System: Rich event emission for lifecycle hooks and user interactions
  • Directive Support: Custom directives for advanced positioning (appendToBody)
  • Accessibility Layer: Full ARIA support with proper roles, labels, and keyboard navigation

Capabilities

Core Selection

Essential selection functionality supporting both single and multiple selection modes, with comprehensive value management and state tracking.

// Main component props for selection
props: {
  value: Object | String | null,     // Currently selected value(s)
  multiple: Boolean,                 // Enable multiple selection
  options: Array,                    // Available options array
  disabled: Boolean,                 // Disable component
  clearable: Boolean,                // Show clear button
  inputId: String,                   // Input element id attribute
  resetOnOptionsChange: Boolean | Function // Control value reset behavior
}

// Core selection methods
methods: {
  select(option: Object | String): void,
  deselect(option: Object | String): void,
  clearSelection(): void
}

// Selection events
events: {
  'input': (value: any) => void,           // v-model value change
  'option:selected': (option: any) => void, // Option selected
  'option:deselected': (option: any) => void // Option deselected
}

Core Selection

Search and Filtering

Built-in search functionality with customizable filtering logic, supporting real-time option filtering and custom match algorithms.

// Search and filter props
props: {
  searchable: Boolean,              // Enable search input
  filterable: Boolean,             // Enable option filtering
  filterBy: Function,              // Custom filter matching logic
  filter: Function,               // Complete filter implementation
  clearSearchOnSelect: Boolean,   // Clear search on selection
  clearSearchOnBlur: Function    // Clear search on blur
}

// Search methods and computed properties
computed: {
  searching: Boolean,            // Current search state
  searchPlaceholder: String,     // Computed placeholder text
  filteredOptions: Array        // Options filtered by search
}

// Search events
events: {
  'search:focus': () => void,
  'search:blur': () => void,
  'search': (searchText: String, toggleLoading: Function) => void
}

Search and Filtering

Tagging and Creation

Dynamic option creation functionality allowing users to create new options from search input, with customizable creation logic and tag management.

// Tagging props
props: {
  taggable: Boolean,           // Enable option creation
  pushTags: Boolean,          // Add created tags to options
  createOption: Function      // Custom option creation logic
}

// Tagging methods
methods: {
  pushTag(option: Object | String): void,
  optionExists(option: Object | String): Boolean
}

// Creation events
events: {
  'option:created': (option: Object | String) => void
}

Tagging and Creation

Keyboard Navigation

Complete keyboard navigation system with customizable key mappings, type-ahead functionality, and accessibility compliance.

// Keyboard props
props: {
  selectOnKeyCodes: Array,        // Key codes for selection
  mapKeydown: Function,          // Custom keydown mapping
  tabindex: Number,              // Input tabindex
  autoscroll: Boolean            // Auto-scroll to highlighted option
}

// Navigation methods (from typeAheadPointer mixin)
methods: {
  typeAheadUp(): void,
  typeAheadDown(): void, 
  typeAheadSelect(): void,
  typeAheadToLastSelected(): void
}

// Navigation data
data: {
  typeAheadPointer: Number      // Current keyboard pointer position
}

Keyboard Navigation

Customization and Styling

Extensive customization options through slots, component overrides, SCSS variables, and custom positioning for advanced use cases.

// Customization props
props: {
  components: Object,           // Override child components
  placeholder: String,         // Placeholder text
  transition: String,          // Dropdown transition
  dir: String,                // Text direction (ltr/rtl/auto)
  appendToBody: Boolean,      // Append dropdown to body
  calculatePosition: Function  // Custom positioning logic
}

// Available slots
slots: {
  'header': Object,
  'selected-option-container': { option, deselect, multiple, disabled },
  'selected-option': Object,
  'search': Object,
  'open-indicator': Object,
  'spinner': Object,
  'list-header': Object,
  'option': Object,
  'no-options': Object,
  'list-footer': Object,
  'footer': Object
}

Customization and Styling

AJAX and Loading States

Built-in support for asynchronous data loading with loading state management, search event handling, and server-side filtering integration.

// AJAX props (from ajax mixin)
props: {
  loading: Boolean             // Show loading state
}

// Loading methods
methods: {
  toggleLoading(toggle?: Boolean): Boolean
}

// AJAX events
events: {
  'search': (searchText: String, toggleLoading: Function) => void
}

// Loading data
data: {
  mutableLoading: Boolean     // Internal loading state
}

AJAX and Loading

Types

// Core component interface
interface VueSelect extends Vue {
  // Props
  value?: Object | String | null;
  multiple?: Boolean;
  options?: Array;
  disabled?: Boolean;
  searchable?: Boolean;
  // ... (full prop list available in sub-docs)
  
  // Data
  search: String;
  open: Boolean;
  typeAheadPointer: Number;
  
  // Methods
  select(option: Object | String): void;
  deselect(option: Object | String): void;
  clearSelection(): void;
  toggleDropdown(event: Event): void;
  // ... (full method list available in sub-docs)
}

// Option value types
type OptionValue = String | Number | Object;

// Filter function signature
type FilterFunction = (options: Array, search: String) => Array;

// Reduce function signature  
type ReduceFunction = (option: Object) => any;

// Option creation function signature
type CreateOptionFunction = (option: String) => Object | String;