From 3cf41402ef648ee7dd42c6f0c5c921ddb72e483f Mon Sep 17 00:00:00 2001
From: Jeff Sagal <sagalbot@gmail.com>
Date: Sun, 17 Oct 2021 13:38:36 -0700
Subject: [PATCH] docs: customizing dropdown behaviour (#1520)

---
 .../components/OpenWhenSearchTextPresent.vue  | 29 +++++++++++++++++++
 docs/.vuepress/config/themeConfig.js          |  1 +
 docs/guide/opening.md                         | 22 ++++++++++++++
 3 files changed, 52 insertions(+)
 create mode 100644 docs/.vuepress/components/OpenWhenSearchTextPresent.vue
 create mode 100644 docs/guide/opening.md

diff --git a/docs/.vuepress/components/OpenWhenSearchTextPresent.vue b/docs/.vuepress/components/OpenWhenSearchTextPresent.vue
new file mode 100644
index 0000000..4e799b5
--- /dev/null
+++ b/docs/.vuepress/components/OpenWhenSearchTextPresent.vue
@@ -0,0 +1,29 @@
+<template>
+  <v-select
+    v-model="country"
+    :options="countries"
+    :dropdown-should-open="dropdownShouldOpen"
+  />
+</template>
+
+<script>
+import countries from '../data/countries.js'
+
+export default {
+  data() {
+    return {
+      countries,
+      country: null,
+    }
+  },
+  methods: {
+    dropdownShouldOpen(VueSelect) {
+      if (this.country !== null) {
+        return VueSelect.open
+      }
+
+      return VueSelect.search.length !== 0 && VueSelect.open
+    },
+  },
+}
+</script>
diff --git a/docs/.vuepress/config/themeConfig.js b/docs/.vuepress/config/themeConfig.js
index 456abcf..de97e72 100644
--- a/docs/.vuepress/config/themeConfig.js
+++ b/docs/.vuepress/config/themeConfig.js
@@ -59,6 +59,7 @@ module.exports = {
         children: [
           ['guide/keydown', 'Keydown Events'],
           ['guide/positioning', 'Dropdown Position'],
+          ['guide/opening', 'Dropdown Opening'],
           ['guide/filtering', 'Option Filtering'],
         ],
       },
diff --git a/docs/guide/opening.md b/docs/guide/opening.md
new file mode 100644
index 0000000..40613ab
--- /dev/null
+++ b/docs/guide/opening.md
@@ -0,0 +1,22 @@
+## Default Dropdown Behaviour
+
+By default, the dropdown will open anytime the underlying search input has focus. The dropdown will
+open when clicked, or when it has received focus when tabbing through inputs.
+
+## Customizing Dropdown Behaviour <Badge text="v3.12.0+" />
+
+The `dropdownShouldOpen` prop allows for full customization of the open/close behaviour. The prop
+accepts a `function` that should return a `boolean` value. The returned boolean value will be used
+to determine if the dropdown should be `open`/`true` or `false`/`closed`. The function receives the
+instance of the component as the only argument.
+
+#### Example: Open the dropdown when search text is present
+--- 
+
+In this example, we will wait to show the dropdown until the user has started typing. However, if a
+country has already been selected, we will display the dropdown right away.
+
+<OpenWhenSearchTextPresent />
+
+<<< @/.vuepress/components/OpenWhenSearchTextPresent.vue
+