mirrors/vue-select
2
0
Fork 0
mirror of https://github.com/tenrok/vue-select.git synced 2026-05-17 02:29:37 +03:00
Code Activity

feat: merge upstream into beta channel (#1589)

Browse Source
This commit is contained in:
Jeff Sagal
2022-02-18 13:55:34 -08:00
committed by GitHub
parent 7a3b373d43
commit ff2806876d
40 changed files with 2565 additions and 3146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.vuepress/components/CssVariables.vue
+31
View File
@@ -0,0 +1,31 @@
<template>
<div style="background: #282c34; padding: 1rem; border-radius: 0.3rem">
<v-select :options="countries" />
</div>
</template>
<script>
import countries from '../data/countries.js'
export default {
data: () => ({ countries }),
}
</script>
<style scoped>
>>> {
--vs-controls-color: #664cc3;
--vs-border-color: #664cc3;
--vs-dropdown-bg: #282c34;
--vs-dropdown-color: #cc99cd;
--vs-dropdown-option-color: #cc99cd;
--vs-selected-bg: #664cc3;
--vs-selected-color: #eeeeee;
--vs-search-input-color: #eeeeee;
--vs-dropdown-option--active-bg: #664cc3;
--vs-dropdown-option--active-color: #eeeeee;
}
</style>
docs/.vuepress/components/ReducedWithNoMatchingOption.vue
+20
View File
@@ -0,0 +1,20 @@
<template>
<v-select
v-model="selected"
:reduce="(option) => option.id"
:options="[
{ label: 'One', id: 1 },
{ label: 'Two', id: 2 },
]"
/>
</template>
<script>
export default {
data() {
return {
selected: 3,
}
},
}
</script>
docs/guide/css.md
+48 -17
View File
@@ -1,17 +1,47 @@
Vue Select offers many APIs for customizing the look and feel from the component. You can use
[scoped slots](../api/slots.md), [custom child components](components.md), or modify the built in
SCSS variables.
Vue Select offers many APIs for customizing the look and feel from the component. You can use
[scoped slots](../api/slots.md), [custom child components](components.md), or modify the built in
CSS properties.
::: tip
Support for CSS variables (custom properties) is currently on the road map for those
that are not using sass in their projects.
:::
## CSS Variables
## SCSS Variables
Vue Select uses custom CSS properties throughout the component to handle visual opinions. This
allows for quite a bit of flexibility in styling, without having to hook into a build system for
generating your own styles with something like SASS. If there is a value that you think should use a
CSS property instead of a hardcoded CSS value, please submit a PR.
## Dark Mode Example
Without writing any CSS yourself, you can completely customize the look and feel of Vue Select
through the use of CSS variables. In this example, we adjust the colors of the component to match
for a dark mode application.
In this case, the variables are scoped to only this implementation of the component, but you could
place these variables anywhere in your applications CSS file to implement at a global level for your
app.
Check the MDN docs for more info
about [CSS Custom Properties.](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
<CssVariables style="margin-top: 1rem;" />
<<< @/.vuepress/components/CssVariables.vue
### Available CSS Variables <Badge type="primary">3.18+</Badge>
<<< @/../src/css/global/variables.css
## SCSS <Badge type="warning">Deprecated in v3.18</Badge>
::: warning Deprecation Notice
The SCSS build been deprecated for the `v3.x` release, and will be
removed in `v4.0.0`. The files will remain in the v3 codebase if you really need them, but the
recommended approach is to leverage the included CSS variables instead.
:::
Variables are leveraged in as much of the component styles as possible. If you really want to dig
into the SCSS, the files are located in `src/scss`. The variables listed below can be found at
[`src/scss/global/_variables`](https://github.com/sagalbot/vue-select/blob/master/src/scss/global/_variables.scss).
[`src/scss/global/_variables`](https://github.com/sagalbot/vue-select/blob/master/src/scss/global/_variables.scss)
.
All variables are implemented with `!default` in order to make them easier to override in your
application.
@@ -23,12 +53,12 @@ application.
Vue Select takes the approach of using selectors with a single level of specificity, while using
classes that are very specific to Vue Select to avoid collisions with your app.
All classes within Vue Select use the `vs__` prefix, and selectors are generally a single classname
Most classes within Vue Select use the `vs__` prefix, and selectors are generally a single classname
– unless there is a state being applied to the component.
In order to override a default property in your app, you should add one level of specificity.
The easiest way to do this, is to add `.v-select` before the `vs__*` selector if you want to adjust
all instances of Vue Select, or add your own classname if you just want to affect one.
In order to override a default property in your app, you should add one level of specificity. The
easiest way to do this, is to add `.v-select` before the `vs__*` selector if you want to adjust all
instances of Vue Select, or add your own classname if you just want to affect one.
<CssSpecificity />
@@ -38,17 +68,18 @@ all instances of Vue Select, or add your own classname if you just want to affec
By default, the dropdown transitions with a `.15s` cubic-bezier opacity fade in/out. The component
uses the [VueJS transition system](https://vuejs.org/v2/guide/transitions.html). By default, the
transition name is `vs__fade`. There's a couple ways to override or change this transition.
transition name is `vs__fade`. There's a couple ways to override or change this transition.
1. Use the `transition` prop. Applying this prop will change the name of the animation classes and
negate the default CSS. If you want to remove it entirely, you can set it to an empty string.
negate the default CSS. If you want to remove it entirely, you can set it to an empty string.
```html
<v-select transition="" />
```
2. You can also override the default CSS for the `vs__fade` transition. Again, if you
wanted to eliminate the transition entirely:
2. You can also override the default CSS for the `vs__fade` transition. Again, if you wanted to
eliminate the transition entirely:
```css
.vs__fade-enter-active,
docs/guide/install.md
+9 -9
View File
@@ -1,8 +1,14 @@
## Yarn / NPM
Install with yarn:
Install with yarn or npm:
```bash
# vue 2
yarn add vue-select
# vue 3
yarn add vue-select@beta
# or, using NPM
npm install vue-select
```
@@ -22,12 +28,6 @@ The component itself does not include any CSS. You'll need to include it separat
import 'vue-select/dist/vue-select.css';
```
Alternatively, you can import the scss for complete control of the component styles:
```scss
@import "vue-select/src/scss/vue-select.scss";
```
## In the Browser
vue-select ships as an UMD module that is accessible in the browser. When loaded
@@ -56,5 +56,5 @@ Vue.component('v-select', VueSelect.VueSelect);
## Vue Compatibility
- If you're on Vue `1.x`, use vue-select `1.x`.
- The `1.x` branch has not received updates since the 2.0 release.
- Vue `2.x`, use vue-select `3.x`.
- Vue `3.x`, use vue-select `3.x@beta`.
docs/guide/values.md
+92 -59
View File
@@ -2,11 +2,12 @@
### `v-model`
The most common use case for vue-select is to have the chosen value synced with a parent component. vue-select
takes advantage of the `v-model` syntax to sync values with a parent. The `v-model` syntax works with
primitives and objects.
The most common use case for vue-select is to have the chosen value synced with a parent component.
vue-select takes advantage of the `v-model` syntax to sync values with a parent. The `v-model`
syntax works with primitives and objects.
```html
<v-select v-model="selected" />
```
@@ -14,25 +15,26 @@ Note that when using the `multiple` prop, the `v-model` value will always be an
### Props and Events
Sometimes `v-model` might not fit your use case. For example, when working with [Vuex](https://vuex.vuejs.org),
you'll need to trigger a mutation rather than mutating a value directly. In that case, maybe you need
to bind a pre-selected value, and trigger a mutation when it changes.
Sometimes `v-model` might not fit your use case. For example, when working
with [Vuex](https://vuex.vuejs.org), you'll need to trigger a mutation rather than mutating a value
directly. In that case, maybe you need to bind a pre-selected value, and trigger a mutation when it
changes.
vue-select exposes the `value` prop and an `input` event to enable this. This combo of props and
vue-select exposes the `value` prop and an `input` event to enable this. This combo of props and
events is also how Vue wires up the `v-model` syntax internally.
#### Prop: `value`
The `value` prop lets vue-select know what value is currently selected. It will accept strings,
numbers or objects. If you're using a `multiple` v-select, you'll want to pass an array.
The `value` prop lets vue-select know what value is currently selected. It will accept strings,
numbers or objects. If you're using a `multiple` v-select, you'll want to pass an array.
```html
<v-select :value="selected" />
```
::: tip 🤓
Anytime you bind the `value` prop directly, you're responsible for updating the bound variable
in your code using the `@input` event.
::: tip 🤓 Anytime you bind the `value` prop directly, you're responsible for updating the bound
variable in your code using the `@input` event.
:::
#### Event: `input`
@@ -42,50 +44,66 @@ state as it's only parameter.
#### Vuex Support
The `value` prop and `emit` event are very useful when using a state management tool, like Vuex.
You can bind the selected value with `:value="$store.myValue"`, and use the `input` event to
trigger a mutation, or dispatch an action – or anything else you might need to do when the selection
changes.
The `value` prop and `emit` event are very useful when using a state management tool, like Vuex. You
can bind the selected value with `:value="$store.myValue"`, and use the `input` event to trigger a
mutation, or dispatch an action – or anything else you might need to do when the selection changes.
```html
<v-select :value="$store.myValue" @input="setSelected" />
```
```js
methods: {
setSelected(value) {
// trigger a mutation, or dispatch an action
}
setSelected(value)
{
// trigger a mutation, or dispatch an action
}
}
```
## Single/Multiple
By default, vue-select supports choosing a single value. If you need multiple values, use the
`multiple` boolean prop, much the same way you would on an HTML `<select>` element. When `multiple`
is true, `v-model` and `value` must be an array.
```html
<v-select multiple v-model="selected" :options="['Canada','United States']" />
```
<v-select multiple :options="['Canada','United States']" />
## Transforming Selections
When the `options` array contains objects, vue-select returns the whole object as dropdown value
When the `options` array contains objects, vue-select returns the whole object as dropdown value
upon selection. This approach makes no assumptions about the data you need, and provides a lot of
flexibility. However, there will be situations where maybe you just need to return a single key
from an object.
flexibility. However, there will be situations where you just need to return a single key from an
object.
### Returning a single key with `reduce`
### Returning a single key with `reduce`
If you need to return a single key, or transform the selection before it is synced, vue-select
provides a `reduce` callback that allows you to transform a selected option before it is passed to
If you need to return a single key, or transform the selection before it is synced, vue-select
provides a `reduce` callback that allows you to transform a selected option before it is passed to
the `@input` event. Consider this data structure:
```js
let options = [{code: 'CA', country: 'Canada'}];
```
If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce`
If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce`
prop to receive only the data that's required.
```html
<v-select :options="options" :reduce="country => country.code" label="country" />
<v-select :options="options" :reduce="country => country.code" label="country" />
```
### Deep Nested Values
The `reduce` property also works well when you have a deeply nested value:
```
{
country: 'canada',
@@ -95,30 +113,42 @@ The `reduce` property also works well when you have a deeply nested value:
}
}
```
```html
<v-select :options="options" :reduce="country => country.meta.code" label="country" />
<v-select :options="options" :reduce="country => country.meta.code" label="country" />
```
<reducer-nested-value />
## Single/Multiple Selection
## Caveats with `reduce`
By default, vue-select supports choosing a single value. If you need multiple values, use the
`multiple` boolean prop, much the same way you would on an HTML `<select>` element. When `multiple`
is true, `v-model` and `value` must be an array.
The most common issue with `reduce` is when the component displays your _reduced_ _value_ instead of
it's _label_. This happens when you supply Vue Select a `value` or `v-model` binding with a reduced_
value, but the complete option object is not present in the `options` array.
```html
<v-select multiple v-model="selected" :options="['Canada','United States']" />
```
<v-select multiple :options="['Canada','United States']" />
<ReducedWithNoMatchingOption />
<<< @/.vuepress/components/ReducedWithNoMatchingOption.vue
In the example above, the component was supplied with an ID that doesn't exist in the `options`
array. When `value` changes, Vue Select searches the supplied options, running each one
through `reduce` until the corresponding option is found. When that option doesn't exist, Vue Select
will end up displaying the `value` supplied.
::: warning
When providing Vue Select with a _reduced_ `value` - the object that the value was reduced from must
exist in the `options` array.
:::
## Tagging
To allow input that's not present within the options, set the `taggable` prop to true.
```html
<v-select taggable multiple />
```
@@ -127,6 +157,7 @@ To allow input that's not present within the options, set the `taggable` prop to
If you want added tags to be pushed to the options array, set `push-tags` to true.
```html
<v-select taggable multiple push-tags />
```
@@ -136,10 +167,11 @@ If you want added tags to be pushed to the options array, set `push-tags` to tru
When combining `taggable` with `reduce`, you must define the `createOption` prop. The
`createOption` function is responsible for defining the structure of the objects that Vue Select
will create for you when adding a tag. It should return a value that has the same properties as the
will create for you when adding a tag. It should return a value that has the same properties as the
rest of your `options`.
If you don't define `createOption`, Vue Select will construct a simple object following this structure:
If you don't define `createOption`, Vue Select will construct a simple object following this
structure:
`{[this.label]: searchText}`. If you're using `reduce`, this is probably not what your options look
like, which is why you'll need to set the function yourself.
@@ -147,28 +179,29 @@ like, which is why you'll need to set the function yourself.
We have a taggable select for adding books to a collection. We're just concerned about getting the
book title added, and our server side code will add the author details in a background process. The
user has already selected a book.
user has already selected a book.
```js
const options = [
{
title: "HTML5",
author: {
firstName: "Remy",
lastName: "Sharp"
{
title: "HTML5",
author: {
firstName: "Remy",
lastName: "Sharp"
}
}
}
];
```
```html
<v-select
taggable
multiple
label="title"
:options="options"
:create-option="book => ({ title: book, author: { firstName: '', lastName: '' } })"
:reduce="book => `${book.author.firstName} ${book.author.lastName}`"
taggable
multiple
label="title"
:options="options"
:create-option="book => ({ title: book, author: { firstName: '', lastName: '' } })"
:reduce="book => `${book.author.firstName} ${book.author.lastName}`"
/>
```
docs/package.json
-2
View File
@@ -22,9 +22,7 @@
"dotenv": "^8.2.0",
"fuse.js": "^6.4.0",
"gh-pages": "^2.2.0",
"node-sass": "^4.12.0",
"octonode": "^0.9.5",
"sass-loader": "^8.0.2",
"vue": "^2.6.10",
"vuepress": "^1.4.0",
"vuex": "^3.1.0"
docs/yarn.lock
+26 -574
View File
File diff suppressed because it is too large Load Diff