2
0
mirror of https://github.com/tenrok/vue-select.git synced 2026-06-10 07:52:23 +03:00

- add docs script to serve docs

- WIP updates to docs
- add vuejs theme
This commit is contained in:
Jeff
2017-10-01 13:22:50 -07:00
parent 365a5ee26d
commit 018f3f7697
23 changed files with 649 additions and 126 deletions
+2
View File
@@ -5,3 +5,5 @@ npm-debug.log
test/unit/coverage
.coveralls.yml
.flowconfig
docs/_book
docs/node_modules
+18
View File
@@ -0,0 +1,18 @@
### Change Event <small>Vuex Compatibility</small>
`vue-select` provides a `change` event. This function is passed the currently selected value(s) as it's only parameter.
This is very useful when integrating with Vuex, as it will allow your to trigger an action to update your vuex state object. Choose a callback and see it in action.
```html
<v-select v-on:change="consoleCallback" :options="countries"></v-select>
```
```js
methods: {
consoleCallback(val) {
console.dir(JSON.stringify(val))
},
}
```
View File
+1
View File
@@ -0,0 +1 @@
## Getting Started
View File
+36
View File
@@ -0,0 +1,36 @@
## Dropdown Options {#options}
`vue-select` accepts arrays of strings or objects to use as options through the `options` prop:
```html
<v-select :options="['foo','bar']"></v-select>
```
When provided an array of objects, `vue-select` will display a single value of the object. By default, `vue-select` will look for a key named `label` on the object to use as display text.
```html
<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
```
### Option Labels {#labels}
When the `options` array contains objects, `vue-select` looks for the `label` key to display by default. You can set your own label to match your source data using the `label` prop.
For example, consider an object with `countryCode` and `countryName` properties:
```json
{
countryCode: "CA",
countryName: "Canada"
}
```
If you wanted to display `Canada` in the dropdown, you'd use the `countryName` key:
```html
<v-select label="countryName" :options="countries"></v-select>
```
### Null / Empty Options {#emptyOptions}
`vue-select` requires the `option` property to be an `array`. If you are using Vue in development mode, you will get warnings attempting to pass anything other than an `array` to the `options` prop. If you need a `null`/`empty` value, use an empty array `[]`.
+23
View File
@@ -0,0 +1,23 @@
## Selecting Values {#values}
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.
```html
<v-select v-model="selected"></v-select>
```
If you don't require the `value` to be synced, you can also pass the prop directly:
```html
<v-select :value="selected"></v-select>
```
This method allows you to pre-select a value(s), without syncing any changes to the parent component.
### Single/Multiple Selection {#multiple}
By default, `vue-select` supports choosing a single value. If you need multiple values, use the `multiple` prop:
```html
<v-select multiple :options="countries"></v-select>
```
-9
View File
@@ -1,9 +0,0 @@
### Custom Labels
By default when the `options` array contains objects, `vue-select` looks for the `label` key for display. If your data source doesn't contain that key, you can set your own using the `label` prop.
On this page, the list of countries used in the examples contains `value` and `label` properties: `{value: "CA", label: "Canada"}`. In this example, we'll display the country code instead of the label.
`<v-select label="value" :options="countries"></v-select>`
<v-select label="value" :options="countries"></v-select>
+19
View File
@@ -0,0 +1,19 @@
- [HTML5 Validation](#validation)
- [Vuex](#vuex)
- [AJAX](#ajax)
- [Dependent vSelects](#dependent)
- [Custom Component with Mixins](#customComponent)
## HTML5 Validation {#validation}
## Vuex {#vuex}
[](codepen://sagalbot/aJQJyp?height=500&theme=0)
## AJAX {#ajax}
## Dependent vSelects {#dependent}
## Custom Component with Mixins {#customComponent}
+9 -25
View File
@@ -1,36 +1,20 @@
## Vue Compatibility
- `vue ~2.0` use `vue-select ~2.0`
- `vue ~1.0` use `vue-select ~1.0`
## NPM Based WorkFlows
``` bash
```bash
$ npm install vue-select
```
```html
<template>
<div id="myApp">
<v-select v-model="selected" :options="options"></v-select>
</div>
</template>
<script>
import vSelect from 'vue-select'
export default {
components: {vSelect},
data() {
return {
selected: null,
options: ['foo','bar','baz']
}
}
}
</script>
```
## Browser Globals
`v1.3.0+` no longer requires any toolchain to use the component:
Just include `vue` & `vue-select.js` - I recommend using [unpkg.com](https://unpkg.com/#/).
Include `vue` & `vue-select.js` - I recommend using [unpkg.com](https://unpkg.com/#/).
```html
<!-- include VueJS first -->
<script src="https://unpkg.com/vue@latest"></script>
<!-- use the latest release -->
<script src="https://unpkg.com/vue-select@latest"></script>
<!-- or point to a specific release -->
+26
View File
@@ -0,0 +1,26 @@
# vue-select [![Build Status](https://travis-ci.org/sagalbot/vue-select.svg?branch=master)](https://travis-ci.org/sagalbot/vue-select) [![Code Score](https://img.shields.io/codeclimate/github/sagalbot/vue-select.svg?style=flat-square)](https://lima.codeclimate.com/github/sagalbot/vue-select) [![Code Coverage](https://img.shields.io/codeclimate/coverage/github/sagalbot/vue-select.svg?style=flat-square)](https://codeclimate.com/github/sagalbot/vue-select) [![No Dependencies](https://img.shields.io/gemnasium/sagalbot/vue-select.svg?style=flat-square)](https://gemnasium.com/github.com/sagalbot/vue-select) ![MIT License](https://img.shields.io/github/license/sagalbot/vue-select.svg?style=flat-square) ![Current Release](https://img.shields.io/github/release/sagalbot/vue-select.svg?style=flat-square)
> A native Vue.js select component that provides similar functionality to Select2 without the overhead of jQuery.
#### Features
- AJAX Support
- Tagging
- List Filtering/Searching
- Supports Vuex
- Select Single/Multiple Options
- Tested with Bootstrap 3/4, Bulma, Foundation
- +95% Test Coverage
- ~33kb minified with CSS
- Zero dependencies
## Documentation
- **[Demo & Docs](http://sagalbot.github.io/vue-select/)**
- **[Example on JSBin](http://jsbin.com/saxaru/8/edit?html,js,output)**
- **[CodePen Template](http://codepen.io/sagalbot/pen/NpwrQO)**
- **[Trello Roadmap](https://trello.com/b/vWvITNzS/vue-select)**
## Install
###### Vue Compatibility
- `vue ~2.0` use `vue-select ~2.0`
- `vue ~1.0` use `vue-select ~1.0`
-26
View File
@@ -1,26 +0,0 @@
### Change Event <small>Vuex Compatibility</small>
vue-select provides a `change` event. This function is passed the currently selected value(s) as it's only parameter.
This is very useful when integrating with Vuex, as it will allow your to trigger an action to update your vuex state object. Choose a callback and see it in action.
<div class="form-inline">
<div class="radio"><label><input type="radio" v-model="callback" value="console"> `console.log(val)`</label> </div>
<div class="radio"><label><input type="radio" v-model="callback" value="alert"> `alert(val)`</label> </div>
</div>
```html
<v-select v-on:change="consoleCallback" :options="countries"></v-select>
```
```js
methods: {
consoleCallback(val) {
console.dir(JSON.stringify(val))
},
alertCallback(val) {
alert(JSON.stringify(val))
}
}
```
+223
View File
@@ -0,0 +1,223 @@
```js
/**
* Contains the currently selected value. Very similar to a
* `value` attribute on an <input>.
* @type {Object||String||null}
*/
value: {
default: null
}
/**
* An array of strings or objects to be used as dropdown choices.
* If you are using an array of objects, vue-select will look for
* a `label` key (ex. [{label: 'This is Foo', value: 'foo'}]). A
* custom label key can be set with the `label` prop.
* @type {Array}
*/
options: {
type: Array,
default() {
return []
},
}
/**
* Sets the max-height property on the dropdown list.
* @deprecated
* @type {String}
*/
maxHeight: {
type: String,
default: '400px'
},
/**
* Enable/disable filtering the options.
* @type {Boolean}
*/
searchable: {
type: Boolean,
default: true
},
/**
* Equivalent to the `multiple` attribute on a `<select>` input.
* @type {Object}
*/
multiple: {
type: Boolean,
default: false
},
/**
* Equivalent to the `placeholder` attribute on an `<input>`.
* @type {Object}
*/
placeholder: {
type: String,
default: ''
},
/**
* Sets a Vue transition property on the `.dropdown-menu`. vue-select
* does not include CSS for transitions, you'll need to add them yourself.
* @type {String}
*/
transition: {
type: String,
default: 'fade'
},
/**
* Enables/disables clearing the search text when an option is selected.
* @type {Boolean}
*/
clearSearchOnSelect: {
type: Boolean,
default: true
},
/**
* Close a dropdown when an option is chosen. Set to false to keep the dropdown
* open (useful when combined with multi-select, for example)
* @type {Boolean}
*/
closeOnSelect: {
type: Boolean,
default: true
},
/**
* Tells vue-select what key to use when generating option
* labels when each `option` is an object.
* @type {String}
*/
label: {
type: String,
default: 'label'
},
/**
* Callback to generate the label text. If {option}
* is an object, returns option[this.label] by default.
* @param {Object || String} option
* @return {String}
*/
getOptionLabel: {
type: Function,
default(option) {
if (typeof option === 'object') {
if (this.label && option[this.label]) {
return option[this.label]
}
}
return option;
}
},
/**
* An optional callback function that is called each time the selected
* value(s) change. When integrating with Vuex, use this callback to trigger
* an action, rather than using :value.sync to retreive the selected value.
* @type {Function}
* @default {null}
*/
onChange: {
type: Function,
default: function (val) {
this.$emit('input', val)
}
},
/**
* Enable/disable creating options from searchInput.
* @type {Boolean}
*/
taggable: {
type: Boolean,
default: false
},
/**
* When true, newly created tags will be added to
* the options list.
* @type {Boolean}
*/
pushTags: {
type: Boolean,
default: false
},
/**
* User defined function for adding Options
* @type {Function}
*/
createOption: {
type: Function,
default(newOption) {
if (typeof this.mutableOptions[0] === 'object') {
newOption = {[this.label]: newOption}
}
this.$emit('option:created', newOption)
return newOption
}
},
/**
* When false, updating the options will not reset the select value
* @type {Boolean}
*/
resetOnOptionsChange: {
type: Boolean,
default: false
},
/**
* Disable the dropdown entirely.
* @type {Boolean}
*/
noDrop: {
type: Boolean,
default: false
},
/**
* Sets the id of the input element.
* @type {String}
* @default {null}
*/
inputId: {
type: String
}
```
# AJAX {#ajax}
```js
/**
* Toggles the adding of a 'loading' class to the main
* .v-select wrapper. Useful to control UI state when
* results are being processed through AJAX.
*/
loading: {
type: Boolean,
default: false
},
/**
* Accept a callback function that will be
* run when the search text changes.
*
* loading() accepts a boolean value, and can
* be used to toggle a loading class from
* the onSearch callback.
*
* @param {search} String Current search text
* @param {loading} Function(bool) Toggle loading class
*/
onSearch: {
type: Function,
default: function(search, loading){}
}
```
+17 -1
View File
@@ -1,2 +1,18 @@
# Introduction
# vue-select
[![Build Status](https://travis-ci.org/sagalbot/vue-select.svg?branch=master)](https://travis-ci.org/sagalbot/vue-select) [![Code Score](https://img.shields.io/codeclimate/github/sagalbot/vue-select.svg?style=flat-square)](https://lima.codeclimate.com/github/sagalbot/vue-select) [![Code Coverage](https://img.shields.io/codeclimate/coverage/github/sagalbot/vue-select.svg?style=flat-square)](https://codeclimate.com/github/sagalbot/vue-select) [![No Dependencies](https://img.shields.io/gemnasium/sagalbot/vue-select.svg?style=flat-square)](https://gemnasium.com/github.com/sagalbot/vue-select) ![MIT License](https://img.shields.io/github/license/sagalbot/vue-select.svg?style=flat-square) ![Current Release](https://img.shields.io/github/release/sagalbot/vue-select.svg?style=flat-square)
> A native Vue.js select component that provides similar functionality to Select2 without the overhead of jQuery.
Vue Select was designed to be the Select2 replacement for VueJS.
#### Features
- AJAX Support
- Tagging
- List Filtering/Searching
- Supports Vuex
- Select Single/Multiple Options
- Tested with Bootstrap 3/4, Bulma, Foundation
- +95% Test Coverage
- ~33kb minified with CSS
- Zero dependencies
-19
View File
@@ -1,19 +0,0 @@
### Reactive Options
When the list of options provided by the parent changes, vue-select will react as you'd expect.
<div style="margin-top:0;" class="radio">
<label>
<input type="radio" name="reactive-options" v-model="reactive" :value="countries">
`<v-select :options="countries"></v-select>`
</label>
</div>
<div class="radio">
<label>
<input type="radio" name="reactive-options" v-model="reactive" :value="['foo','bar','baz']">
`<v-select :options="['foo','bar','baz']"></v-select>`
</label>
</div>
<v-select :options="reactive"></v-select>
+24 -1
View File
@@ -1,4 +1,27 @@
# Summary
* [Introduction](README.md)
- [Introduction](README.md)
- [Installation](Install.md)
- [npm](Install.md#npm)
- [cdn](Install.md#cdn)
- [Getting Started](Basics.md)
- [Dropdown Options](Basics/Options.md)
- [Option Labels](Basics/Options.md#labels)
- [Null Options](Basics/Options.md#null)
- [Selecting Values](Basics/Values.md#values)
- [Tagging](Basics/Values.md#tagging)
- [Multiple](Basics/Values.md#multiple)
- [Localization](Basics/Localization.md)
- Digging Deeper
- [Templating](Basics.md#options)
- [Vuex](Basics.md#options)
- [AJAX](Basics.md#options)
- [Mixins](Basics.md#options)
- [Validation](Basics.md#options)
- [Examples](Examples.md)
- API
- [Props](Props/Props.md)
- Events
- Slots
-29
View File
@@ -1,29 +0,0 @@
<article class="doc-row" id="ex-multiple">
### Single/Multiple Selection
<div class="row">
<div class="col-md-6">
#### Single Option Select
```html
<v-select :options="countries"></v-select>
```
</div>
<div class="col-md-6">
#### Multiple Option Select
```html
<v-select multiple :options="countries"></v-select>
```
</div>
</div>
</article>
-15
View File
@@ -1,15 +0,0 @@
### Two-Way Value Syncing
The most common use case for vue-select is being able to sync the components value with a parent component. The `value` property supports two-way data binding to accomplish this. The `.sync` data-binding modifier is completely optional. You may use `value` without a two-way binding to preselect options. Here we have preselected 'Canada' by setting `syncedVal: 'Canada'` on the parent component. The buttons below demonstrate how you can set the `value` from the parent. Current value: <v-code>{{ syncedVal }}</v-code>
<div class="form-group">
`<v-select v-model="syncedVal" :options="countries"></v-select>`
</div>
<div class="form-group">
<v-select v-model="syncedVal" :options="countries"></v-select>
</div>
<div class="form-group">
<button @click="syncedVal = 'United States'" class="btn btn-default">Set to United States</button>
<button @click="syncedVal = 'Canada'" class="btn btn-default">Set to Canada</button>
</div>
+20
View File
@@ -0,0 +1,20 @@
{
"title": "vue-select",
"gitbook": ">3.0.0",
"plugins": ["edit-link", "-fontsettings", "github", "codepen"],
"pluginsConfig": {
"edit-link": {
"base": "https://github.com/sagalbot/vue-select/edit/master/docs",
"label": "Edit This Page"
},
"github": {
"url": "https://github.com/sagalbot/vue-select/"
}
},
"links": {
"sharing": {
"facebook": false,
"twitter": false
}
}
}
+227
View File
@@ -0,0 +1,227 @@
@import url('https://fonts.googleapis.com/css?family=Roboto+Mono|Source+Sans+Pro:300,400,600');
body {
letter-spacing: 0;
color: #34495e;
font-family: 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif;
font-size: 15px;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
color: #34495e;
background-color: #fff;
margin: 0;
}
/* LANGS.md index page */
.book-langs-index {
font-family: 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif;
}
.book-langs-index .inner .languages {
padding: 20px 0px;
}
.book-langs-index .inner .languages li {
float: none;
}
li a {
color: #42b983;
font-weight: 600;
}
/* set correct fonts on sidebar and main page */
.book .book-body .page-wrapper .page-inner section.normal, .book-summary { font-family: 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif; }
/* sidebar */
.book-summary ul.summary li a,
.book-summary ul.summary li span {
color: #7f8c8d;
font-family: 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif;
}
.book .book-summary ul.summary li span {
opacity: 0.6;
cursor: not-allowed;
}
.book-summary ul.summary li.active>a {
color: #42b983;
font-weight: 600;
}
#book-search-input { background-color: #fafafa; }
.book-summary { background-color: #fff; }
/* markdown content found on pages */
.markdown-section h1,
.markdown-section h2,
.markdown-section h3,
.markdown-section h4,
.markdown-section strong {
font-weight: 600;
color: #2c3e50;
}
.markdown-section a {
color: #42b983;
font-weight: 600;
}
.markdown-section p,
.markdown-section ul,
.markdown-section ol {
word-spacing: 0.05em;
}
.markdown-section em {
color: #7f8c8d;
}
.markdown-section pre {
padding: 1.2em 1.4em;
line-height: 1.5em;
margin: 0;
}
.markdown-section code, .markdown-section pre {
font-family: 'Roboto Mono', Monaco, courier, monospace;
-webkit-font-smoothing: initial;
-moz-osx-font-smoothing: initial;
background-color: #f8f8f8;
}
code span.css,
code span.javascript,
code span.html,
span[class^="hljs-"] {
-webkit-font-smoothing: initial;
-moz-osx-font-smoothing: initial;
}
.markdown-section pre>code {
font-size: 0.8em;
display: block;
}
.markdown-section code:after, .markdown-section code:before {
content: none;
letter-spacing: 0.05em;
}
code, pre {
font-family: 'Roboto Mono', Monaco, courier, monospace;
font-size: 0.8em;
background-color: #f8f8f8;
-webkit-font-smoothing: initial;
-moz-osx-font-smoothing: initial;
}
code {
color: #e96900;
padding: 3px 5px;
margin: 0 2px;
border-radius: 2px;
white-space: nowrap;
}
code .token {
min-height: 1.5em;
-webkit-font-smoothing: initial;
-moz-osx-font-smoothing: initial;
}
pre code { position: relative; }
pre code.lang-html:after,
pre code.lang-js:after,
pre code.lang-bash:after,
pre code.lang-css:after {
position: absolute;
top: 0;
right: 0;
color: #ccc;
text-align: right;
font-size: 0.75em;
padding: 5px 10px 0;
line-height: 15px;
height: 15px;
font-weight: 600;
}
pre code.lang-html:after {
content: 'HTML';
}
pre code.lang-js:after {
content: 'JS';
}
pre code.lang-bash:after {
content: 'Shell';
}
pre code.lang-css:after {
content: 'CSS';
}
.content img {
max-width: 100%;
}
.content span.light {
color: #7f8c8d;
}
.content span.info {
font-size: 0.85em;
display: inline-block;
vertical-align: middle;
width: 280px;
margin-left: 20px;
}
.markdown-section h1 {
margin: 0 0 1em;
}
.markdown-section h2 {
margin: 45px 0 0.8em;
padding-bottom: 0.7em;
border-bottom: 1px solid #ddd;
}
.markdown-section h3 {
margin: 52px 0 1.2em;
}
.markdown-section figure,
.markdown-section p,
.markdown-section ul,
.markdown-section ol {
margin: 1.2em 0;
}
.markdown-section p,
.markdown-section ul,
.markdown-section ol {
line-height: 1.6em;
}
.markdown-section ul,
.markdown-section ol {
padding-left: 1.5em;
}
.markdown-section a {
color: #42b983;
font-weight: 600;
}
.markdown-section blockquote {
margin: 2em 0;
padding-left: 20px;
border-left: 4px solid #42b983;
}
.markdown-section blockquote p {
font-weight: 600;
margin-left: 0;
}
.markdown-section iframe {
margin: 1em 0;
}
/* these aren't in gitbook at the moment, but leaving them in for future reference */
img {
border: none;
}
.highlight {
overflow-x: auto;
position: relative;
padding: 0;
background-color: #f8f8f8;
padding: 0.8em 0.8em 0.4em;
line-height: 1.1em;
border-radius: 2px;
}
.highlight table,
.highlight tr,
.highlight td {
width: 100%;
border-collapse: collapse;
padding: 0;
margin: 0;
}
.highlight .gutter {
width: 1.5em;
}
+4 -1
View File
@@ -8,7 +8,7 @@
"license": "MIT",
"scripts": {
"dev": "node build/dev-server.js",
"dev:docs": "node build/dev-server.js --docs",
"docs": "gitbook serve docs",
"build": "node build/build.js",
"lint": "eslint --ext .js,.vue src test/unit/specs",
"test": "karma start test/unit/karma.conf.js --single-run",
@@ -42,6 +42,9 @@
"file-loader": "^0.8.4",
"function-bind": "^1.0.2",
"gh-pages": "^0.11.0",
"gitbook-plugin-codepen": "^0.1.2",
"gitbook-plugin-edit-link": "^2.0.2",
"gitbook-plugin-github": "^3.0.0",
"highlight.js": "^9.9.0",
"html-loader": "^0.4.4",
"html-webpack-plugin": "^2.8.1",