Vue 3 / Component Roadmap

Vue 3 support is currently on the beta release channel. This issue will track the state of progress to the v4 release of the component with support for Vue 3. This issue will be updated when progress has been made or new tasks are discovered.

To install the v4 beta with Vue 3 support:

yarn add vue-select@beta

# or npm

npm install vue-select@beta

This release has been out in the wild for some time now. At this point, things are pretty stable, but I can’t guarantee there won’t be more breaking changes. More on that at the very bottom.

Breaking Changes in v4 beta branch

• value renamed to modelValue to match the Vue 3 v-model syntax
• @input event renamed to update:modelValue
• scss files have been removed and replaced with CSS properties

Remaining Tasks

Now that Vue 3 is the default install, the pressure is on to get support moved off the beta channel and into master for a v4.0 release!

Todo

These items must be completed in order to merge beta into master.

Build / Ecosystem

• remove webpack dependency, switch to vite
  • update imports to include file extensions
• remove jest dependencies, switch to vitest
• write docs
  • v4 upgrade guide
  • breaking change list
• update doc platform
  • pick vitepress or vuepress-next or something else entirely? nuxt? separate repo?
  • install nuxt 3
  • install @nuxt/content
  • migrate markdown files
• versioned docs for v3 / v4
  • https://staging.vue-select.org - new docs will live here until v4 lands
  • https://v3.vue-select.org - existing docs can be deployed here now

Vue 3 Updates

• add emits property
• replace this.$on
• update scoped slot calls
• update template ref syntax in v-for
• new function to determine if component is reducing values

Public API Breaking Changes

• : update v-model syntax
  • value prop -> modelValue
  • input event ->
• drop SASS to CSS with custom properties
  • deprecated on 3.x
  • remove dependencies
  • update docs

---

How You Can Help

The current beta distribution has primarily been a community effort driven by contributors. A huge thanks to the folks that pushed up the new initial PRs, triaged bugs and helped with issues to get to this point. I appreciate it!

There’s quite a bit to do here, and I’m excited to get moving. If you want to see this stuff move faster, the number one thing you can do is sponsor me through GitHub. I freelance full time, so the opportunity costs for me to work on vue-select instead of work for my clients is pretty high. Sponsorship contributions really help!

Outside of sponsoring, please get in touch before working on anything big so we can coordinate efforts - either through discussions or twitter. As always, I’m thrilled to welcome contributors to work on the component, and very grateful for those that do!

---

Wishlist

There are a few areas that the component really needs to improve on separate from Vue 3 support that may require breaking changes:

focus management The open/closed state is currently tied to whether the input has focus. This is bad for accessibility and general UX of forms. This needs to be fixed.

state management Having to manage selected values internally brings with it lots of code, and lots of room for bugs. A much simpler and easier to maintain approach would be to only emit events, don’t manage state internally. This would really shrink the codebase, but in order for the component to be able to select values, the consumer needs to provide a v-model/:modelValue binding, otherwise the component won’t know what’s selected.

prop creep The number of props available continues to grow, which creates challenges for maintenance and edge cases. Many of these props have been added to alter visual opinions, as well as modify default behaviour. With a more robust slot implementation (and probably provide/inject wrapper components like Headless UI) many of the style related props can be removed. Behaviour modification is more challenging.

I’d like to compress the breaking changes for those areas into the v4 release so that the component API is good to go for the next few years, and is in line with the way Vue is evolving. Converting the build to Vite/Vitest is part of that path. I’m going to focus on the critical path items, and if there’s time, I’ll assess the viability whether breaking changes are required in those areas for this release, or if it’s better to address them in a future release. If you’ve got opinions about this, I’d love to hear them.

[amchconsult]

is library dead for Vue 3?

[ankitsinghaniyaz]

Is there a documentation showing how I can use this?