vue-hierarchical-select

A hierarchical (cascading) select component for Vue 3. Enables creating multi-level dropdown selects where each selection reveals more granular options (e.g., Country → State → City).

Features

• Vue 3 Composition API with <script setup>
• Unlimited nesting levels
• Responsive layout (horizontal/vertical based on screen width)
• Customizable styling and transitions
• Flexible data structure configuration
• TypeScript friendly

Demo

https://wdda.github.io/vue-hierarchical-select-3/

Installation

npm install vue-hierarchical-select-3

Setup

Global Registration

import { createApp } from 'vue'
import HierarchicalSelect from 'vue-hierarchical-select-3'
import App from './App.vue'

const app = createApp(App)
app.use(HierarchicalSelect)
app.mount('#app')

Local Registration

import { HierarchicalSelect } from 'vue-hierarchical-select-3'

export default {
  components: {
    HierarchicalSelect
  }
}

Usage

<template>
  <hierarchical-select
    :nodes="nodes"
    :selected="selected"
    :change-select="onSelect"
  />
</template>

<script setup>
import { ref } from 'vue'

const selected = ref(5)

const nodes = ref([
  {
    name: 'Category 1',
    id: 1,
    children: [
      { name: 'Subcategory 1', id: 2 },
      {
        name: 'Subcategory 2',
        id: 3,
        children: [
          { name: 'Item 1', id: 4 },
          { name: 'Item 2', id: 5 }
        ]
      }
    ]
  }
])

const onSelect = (value) => {
  selected.value = value
}
</script>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | nodes | Array | required | Hierarchical data with optional children arrays | | selected | String | Number | '' | Pre-selected value ID | | name | String | 'name[]' | HTML form input name attribute | | option-value | String | 'id' | Property name for option values | | option-name | String | 'name' | Property name for display labels | | option-name-default | String | '- choice -' | Placeholder text for dropdowns | | css-classes | Array | Object | ['vue-hierarchical-select'] | CSS classes for select elements | | css-styles | String | '' | Inline styles for select elements | | change-select | Function | () => {} | Callback on selection change | | max-column-width | Number | 10000 | Breakpoint (px) for row/column layout switch | | transition-name | String | '' | Vue transition name for nested levels | | only-last | Boolean | false | Output only the final leaf selection |

Data Structure

{
  name: 'Display Label',  // Uses option-name prop
  id: 1,                  // Uses option-value prop
  children: [             // Optional nested options
    {
      name: 'Child Label',
      id: 2,
      children: [...]
    }
  ]
}

Custom Styling Example

<hierarchical-select
  :nodes="nodes"
  :css-classes="['uk-select', 'uk-margin-bottom']"
  css-styles="min-width: 200px"
  :max-column-width="768"
/>

License

Licensed under the MIT license.