Add API for overwriting default components (#850)

* implement API for overwriting child components

* add test coverage

* update documentation for Components & Styling

* update docs

* refactor API, update docs

* remove the service worker

* fix tests

docs/guide/components.md

@@ -0,0 +1,94 @@
+Vue Select utilizes child components throughout, and exposes an API to overwrite these components 
+with your own, using the `components` `{Object}` prop. When implementing the `components` prop in 
+your code, Vue Select merge it's default components with any keys that you set in the object.
+
+Your object will be merged with the object that is exported below:
+                   
+<<< @/src/components/childComponents.js{4-7}
+
+You can override the value of any of these keys with your own components.
+
+## Available Components
+
+### Deselect
+
+You may wish to roll your own deselect button. `Deselect` is used within tags on 
+`multiple` selects, and serves as the clear button for single selects. Maybe you just want to use
+a simple `<button>Clear</button>` instead.
+
+```html
+<v-select :components="{Deselect}" />
+``` 
+
+```js
+computed: {
+  Deselect() {
+    return Vue.component('Deselect', {
+      render (createElement) {
+        return createElement('button', 'Clear')
+      }
+    })
+  }
+}
+```
+
+<ClearButtonOverride />
+
+The same approach applies for `multiple` selects:
+
+<MultipleClearButtonOverride />
+
+### OpenIndicator
+
+The `OpenIndicator` component is the 'caret' used within the component that adjusts orientation
+based on whether the dropdown is open or closed.
+
+```html
+<v-select :components="{OpenIndicator}" />
+```
+```js
+computed: {
+  OpenIndicator () {
+    return Vue.component('OpenIndicator', {
+      render (createElement) {
+        return createElement('button', '🤘🏻');
+      },
+    });
+  },
+},
+```
+
+<OpenIndicatorOverride />
+
+## Setting at Registration
+
+If you want to all instances of Vue Select to use your custom components throughout your app, while
+only having to set the implementation once, you can do so when registering Vue Select as a component.
+
+```js
+import Vue from 'vue';
+import vSelect from 'vue-select';
+
+/**
+* Create custom components to override defaults.
+* @type {{OpenIndicator: *, Deselect: *}}
+*/
+const components = {
+  Deselect: Vue.component('Deselect', {
+    render: (createElement) => createElement('button', '❌'),
+  }),
+  OpenIndicator: Vue.component('OpenIndicator', {
+    render: (createElement) => createElement('span', '🔽'),
+  }),
+};
+
+// Set the components prop default to return our fresh components 
+vSelect.props.components.default = () => components;
+
+// Register the component
+Vue.component(vSelect)
+```
+
+<CustomComponentRegistration />
+
+

docs/guide/css.md

@@ -0,0 +1,37 @@
+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. 
+
+::: tip
+Support for CSS variables (custom properties) is currently on the road map for those
+that are not using sass in their projects. 
+::: 
+
+## SCSS Variables
+
+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).
+
+All variables are implemented with `!default` in order to make them easier to override in your
+application.
+
+<<< @/src/scss/global/_variables.scss
+
+## Overriding Default Styles
+
+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 
+– 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.
+
+<CssSpecificity />  
+
+<<< @/docs/.vuepress/components/CssSpecificity.vue
+
+

docs/guide/slots.md

@@ -1,3 +1,9 @@
+::: tip 🚧
+This section of the guide is a work in progress! Check back soon for an update.
+Vue Select currently offers quite a few scoped slots, and you can check out the 
+[API Docs for Slots](../api/slots.md) in the meantime while a good guide is put together.
+:::
+
 #### Scoped Slot `option`
 
 vue-select provides the scoped `option` slot in order to create custom dropdown templates.