From 900cbae3e3c57e1a583bfe13048318f96eadfa7c Mon Sep 17 00:00:00 2001
From: Chris Adams <chris@formkit.com>
Date: Wed, 28 Feb 2024 15:42:27 +0100
Subject: [PATCH 01/34] add: initial docs for currency and unit inputs

---
 .examples/currency/currency-default.vue       |  17 ++
 .examples/currency/currency-props-explore.vue |  27 ++++
 .examples/currency/currency-simple-locale.vue |  47 ++++++
 .examples/unit/unit-default.vue               |  25 +++
 .examples/unit/unit-type-switcher.vue         |  38 +++++
 inputs/currency.md                            | 146 ++++++++++++++++++
 inputs/unit.md                                | 144 +++++++++++++++++
 7 files changed, 444 insertions(+)
 create mode 100644 .examples/currency/currency-default.vue
 create mode 100644 .examples/currency/currency-props-explore.vue
 create mode 100644 .examples/currency/currency-simple-locale.vue
 create mode 100644 .examples/unit/unit-default.vue
 create mode 100644 .examples/unit/unit-type-switcher.vue
 create mode 100644 inputs/currency.md
 create mode 100644 inputs/unit.md

diff --git a/.examples/currency/currency-default.vue b/.examples/currency/currency-default.vue
new file mode 100644
index 00000000..80890c30
--- /dev/null
+++ b/.examples/currency/currency-default.vue
@@ -0,0 +1,17 @@
+<script setup>
+import { ref } from 'vue'
+const value = ref(false)
+</script>
+
+<template>
+  <!--
+    FormKit forms auto-collect values of children inputs.
+    Wrap the example in a form so we can display the form values.
+  -->
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <!-- %partial%::html:: -->
+    <FormKit type="currency" name="currency" />
+    <!-- %partial%::html:: -->
+    <pre wrap>{{ value }}</pre>
+  </FormKit>
+</template>
diff --git a/.examples/currency/currency-props-explore.vue b/.examples/currency/currency-props-explore.vue
new file mode 100644
index 00000000..59fdac0b
--- /dev/null
+++ b/.examples/currency/currency-props-explore.vue
@@ -0,0 +1,27 @@
+<script setup>
+import { ref } from 'vue'
+const value = ref(false)
+</script>
+
+<template>
+  <!--
+    FormKit forms auto-collect values of children inputs.
+    Wrap the example in a form so we can display the form values.
+  -->
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <!-- %partial%::html:: -->
+    <FormKit
+      type="currency"
+      name="currency"
+      min="-10"
+      max="1000"
+      step="0.0001"
+      currency="USD"
+      displayLocale="en-US"
+      decimals="4"
+      minDecimals="2"
+    />
+    <!-- %partial%::html:: -->
+    <pre wrap>{{ value }}</pre>
+  </FormKit>
+</template>
diff --git a/.examples/currency/currency-simple-locale.vue b/.examples/currency/currency-simple-locale.vue
new file mode 100644
index 00000000..70b238b5
--- /dev/null
+++ b/.examples/currency/currency-simple-locale.vue
@@ -0,0 +1,47 @@
+<script setup>
+import { ref } from 'vue'
+const value = ref(false)
+</script>
+
+<template>
+  <!--
+    FormKit forms auto-collect values of children inputs.
+    Wrap the example in a form so we can display the form values.
+  -->
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <!-- %partial%::html:: -->
+    <FormKit
+      type="currency"
+      currency="USD"
+      displayLocale="en-US"
+      name="usd"
+      value="12345678.90"
+    />
+
+    <FormKit
+      type="currency"
+      currency="EUR"
+      displayLocale="de-DE"
+      name="eur"
+      value="12345678.90"
+    />
+
+    <FormKit
+      type="currency"
+      currency="INR"
+      displayLocale="en-IN"
+      name="inr"
+      value="12345678.90"
+    />
+
+    <FormKit
+      type="currency"
+      currency="CNY"
+      displayLocale="zh-CN"
+      name="cny"
+      value="12345678.90"
+    />
+    <!-- %partial%::html:: -->
+    <pre wrap>{{ value }}</pre>
+  </FormKit>
+</template>
diff --git a/.examples/unit/unit-default.vue b/.examples/unit/unit-default.vue
new file mode 100644
index 00000000..bb1de13e
--- /dev/null
+++ b/.examples/unit/unit-default.vue
@@ -0,0 +1,25 @@
+<script setup>
+import { ref } from 'vue'
+const value = ref(false)
+</script>
+
+<template>
+  <!--
+    FormKit forms auto-collect values of children inputs.
+    Wrap the example in a form so we can display the form values.
+  -->
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <!-- %partial%::html:: -->
+    <FormKit type="unit" unit="percent" name="percent" value="123.45" />
+    
+    <FormKit type="unit" unit="fahrenheit" name="fahrenheit" value="123.45" />
+    
+    <FormKit type="unit" unit="gigabyte" name="gigabyte" value="123.45" />
+    
+    <FormKit type="unit" unit="kilogram" name="kilogram" displayLocale="de-DE" value="123.45" />
+    
+    <FormKit type="unit" unit="fluid-ounce" name="fluid-ounce" value="123.45" />
+    <!-- %partial%::html:: -->
+    <pre wrap>{{ value }}</pre>
+  </FormKit>
+</template>
diff --git a/.examples/unit/unit-type-switcher.vue b/.examples/unit/unit-type-switcher.vue
new file mode 100644
index 00000000..0286715e
--- /dev/null
+++ b/.examples/unit/unit-type-switcher.vue
@@ -0,0 +1,38 @@
+<script setup>
+import { ref } from 'vue'
+const value = ref(false)
+const unitType = ref('percent')
+const unitOptions = ['acre', 'bit', 'byte', 'celsius', 'centimeter', 'day',
+  'degree', 'fahrenheit', 'fluid-ounce', 'foot', 'gallon', 'gigabit',
+  'gigabyte', 'gram', 'hectare', 'hour', 'inch', 'kilobit', 'kilobyte',
+  'kilogram', 'kilometer', 'liter', 'megabit', 'megabyte', 'meter',
+  'microsecond', 'mile', 'mile-scandinavian', 'milliliter', 'millimeter',
+  'millisecond', 'minute', 'month', 'nanosecond', 'ounce', 'percent',
+  'petabyte', 'pound', 'second', 'stone', 'terabit', 'terabyte', 'week',
+  'yard', 'year']
+</script>
+
+<template>
+  <!--
+    FormKit forms auto-collect values of children inputs.
+    Wrap the example in a form so we can display the form values.
+  -->
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <FormKit
+      type="select"
+      name="unitType"
+      label="Choose a unit type"
+      :options="unitOptions"
+      v-model="unitType"
+    />
+    <!-- %partial%::html:: -->
+    <FormKit
+      type="unit"
+      :unit="unitType"
+      name="percent"
+      value="123.45"
+      :help="`This is a '${unitType}' unit`"
+    />
+    <!-- %partial%::html:: -->
+  </FormKit>
+</template>
diff --git a/inputs/currency.md b/inputs/currency.md
new file mode 100644
index 00000000..aad212a1
--- /dev/null
+++ b/inputs/currency.md
@@ -0,0 +1,146 @@
+---
+title: Currency
+description: The currency input is used to create locale/currency specific parsed content
+---
+
+::InputPageHero
+---
+type: "Currency"
+---
+::
+
+:PageToc
+
+:ProInstallSnippet
+
+## Currency Input
+
+The currency input is used to create locale/currency specific parsed content
+
+::Example
+---
+name: "Currency input defaults"
+file: "_content/_examples/currency/currency-default.vue"
+---
+::
+
+## Props
+
+### Currency
+
+The `currency` prop is the three letter currency code and sets the proper formatting for the specified currency and also sets default decimal places for that currency. For a full list of supported currency types check: https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes
+
+### Locale
+
+By default the locale will use what you have set in your `formkit.config.ts` as the desired locale. However you can override this with the `displayLocale` prop. For example, `en-US`, `de-DE`, `en-IN`, `zh-CN`, etc, etc.
+
+
+::Example
+---
+name: "Currency and Locale settings"
+file: "_content/_examples/currency/currency-simple-locale.vue"
+---
+::
+
+## Currency Additional Props
+
+### Decimals
+
+By default the decimals will display when the value contains the currency/locale decimal separator and will automatically know how many decimal places to display for the given currency, however you can override this. By setting `decimals` to `false` or `0`, the value will not allow decimals.
+
+You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, you always want to show 2 decimal places you would set `minDecimals="2"`.
+
+### Minimum and Maximum Values
+
+Similar to a number input, you can set a `min` and `max` value.
+
+### Step
+
+Again, similar to a number input you can use the up/down keys to step the value. By default the step is `1` but you can override that with this prop.
+
+### Value Formatting
+
+Default value output is the value as a string to reduce issues with large number enumertation issues. However you can format the value as a string and include the currency symbol, grouping, decimal, etc as it is shown in the input.
+
+::Example
+---
+name: "Currecy Prop Exploration"
+file: "_content/_examples/currency/currency-props-explore.vue"
+---
+::
+
+## Props & Attributes
+
+::ReferenceTable
+---
+input: "currency" 
+data: [
+  {
+    prop: "currency",
+    type: "string",
+    default: "USD",
+    description: "Set the specified currency to use for this input"
+  },
+  {
+    prop: "displayLocale",
+    type: "string",
+    default: "en-US",
+    description: "Set the desired display locale to use for this input"
+  },
+  {
+    prop: "decimals",
+    type: "boolean|number",
+    default: "null",
+    description: "Choose to either completely disallow decimals or override the maximum number of decimals for the input"
+  },
+  {
+    prop: "minDecimals",
+    type: "number",
+    default: "null",
+    description: "Choose to show a minimum number of decimals should your input require this"
+  },
+  {
+    prop: "min",
+    type: "number",
+    default: "null",
+    description: "Minimum numeric value allowed. If zero or above, negatives will not be allowed"
+  },
+  {
+    prop: "max",
+    type: "number",
+    default: "null",
+    description: "Maximum numeric value allowed for this input"
+  },
+  {
+    prop: "step",
+    type: "number",
+    default: "1",
+    description: "When using the up/down keys, how much to modify the current value."
+  },
+  {
+    prop: "valueFormat",
+    type: "string",
+    default: "number",
+    description: "Choose between <code>number</code> and <code>string</code> whether you want a numeric value or a parsed string value"
+  },
+]
+---
+::
+
+
+## Sections
+
+:SectionKeysIntro
+
+### Currency input diagram
+
+::FormKitInputDiagram
+---
+prefix-icon-content: ""
+suffix-icon-content: ""
+label-content: "Currency Input"
+input-content: "$1,234.56"
+help-content: "How much do you want to donate?"
+message-content: "That's a lot of money"
+---
+::
diff --git a/inputs/unit.md b/inputs/unit.md
new file mode 100644
index 00000000..3ae6b391
--- /dev/null
+++ b/inputs/unit.md
@@ -0,0 +1,144 @@
+---
+title: Unit
+description: The unit input is used to create locale/currency specific parsed content for percentages, temperatures and measurements
+---
+
+::InputPageHero
+---
+type: "Unit"
+---
+::
+
+:PageToc
+
+:ProInstallSnippet
+
+## Unit Input
+
+The unit input is used to create locale/currency specific parsed content for percentages, temperatures and measurements
+
+::Example
+---
+name: "Unit input defaults"
+file: "_content/_examples/unit/unit-default.vue"
+---
+::
+
+## Props
+
+### Unit
+
+The `unit` prop is the type of unit you want to display from percentages, temperatures, measurements, etc. A full list of allowed unit types are listed below:
+
+::ColumnList
+---
+listItems: ['acre', 'bit', 'byte', 'celsius', 'centimeter', 'day', 'degree', 'fahrenheit', 'fluid-ounce', 'foot', 'gallon', 'gigabit', 'gigabyte', 'gram', 'hectare', 'hour', 'inch', 'kilobit', 'kilobyte', 'kilogram', 'kilometer', 'liter', 'megabit', 'megabyte', 'meter', 'microsecond', 'mile', 'mile-scandinavian', 'milliliter', 'millimeter', 'millisecond', 'minute', 'month', 'nanosecond', 'ounce', 'percent', 'petabyte', 'pound', 'second', 'stone', 'terabit', 'terabyte', 'week', 'yard', 'year']
+---
+::
+
+::Example
+---
+name: "Unit type examples"
+file: "_content/_examples/unit/unit-type-switcher.vue"
+---
+::
+
+### Locale
+
+By default the locale will use what you have set in your `formkit.config.ts` as the desired locale. However you can override this with the `displayLocale` prop. For example, `en-US`, `de-DE`, `en-IN`, `zh-CN`, etc, etc.
+
+## Unit Additional Props
+
+### Decimals
+
+By default the decimals will display when the value contains the unit/locale decimal separator and will show default formatting decimal places to display for the given unit, however you can override this. By setting `decimals` to `false` or `0`, the value will not allow decimals or setting decimals to a numeric value will limit the maximum decimal places to that value.
+
+You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, you always want to show 2 decimal places you would set `minDecimals="2"`.
+
+### Minimum and Maximum Values
+
+Similar to a number input, you can set a `min` and `max` value.
+
+### Step
+
+Again, similar to a number input you can use the up/down keys to step the value. By default the step is `1` but you can override that with this prop.
+
+### Value Formatting
+
+Default value output is the value as a string to reduce issues with large number enumertation issues. However you can format the value as a string and include the currency symbol, grouping, decimal, etc as it is shown in the input.
+
+## Props & Attributes
+
+::ReferenceTable
+---
+input: "unit" 
+data: [
+  {
+    prop: "unit",
+    type: "string",
+    default: "percent",
+    description: "Set the specified unit to use for this input"
+  },
+  {
+    prop: "displayLocale",
+    type: "string",
+    default: "en-US",
+    description: "Set the desired display locale to use for this input"
+  },
+  {
+    prop: "decimals",
+    type: "boolean|number",
+    default: "null",
+    description: "Choose to either completely disallow decimals or override the maximum number of decimals for the input"
+  },
+  {
+    prop: "minDecimals",
+    type: "number",
+    default: "null",
+    description: "Choose to show a minimum number of decimals should your input require this"
+  },
+  {
+    prop: "min",
+    type: "number",
+    default: "null",
+    description: "Minimum numeric value allowed. If zero or above, negatives will not be allowed"
+  },
+  {
+    prop: "max",
+    type: "number",
+    default: "null",
+    description: "Maximum numeric value allowed for this input"
+  },
+  {
+    prop: "step",
+    type: "number",
+    default: "1",
+    description: "When using the up/down keys, how much to modify the current value."
+  },
+  {
+    prop: "valueFormat",
+    type: "string",
+    default: "number",
+    description: "Choose between <code>number</code> and <code>string</code> whether you want a numeric value or a parsed string value"
+  },
+]
+---
+::
+
+
+## Sections
+
+:SectionKeysIntro
+
+### Unit input diagram
+
+::FormKitInputDiagram
+---
+prefix-icon-content: ""
+suffix-icon-content: ""
+label-content: "Unit Input"
+input-content: "1,234.56%"
+help-content: "Help text goes here"
+message-content: "Any messages would appear here"
+---
+::

From 883298d911e90a233e33b83a99c6e78e1de4d9b5 Mon Sep 17 00:00:00 2001
From: Chris Adams <chris@formkit.com>
Date: Mon, 4 Mar 2024 14:15:37 -0500
Subject: [PATCH 02/34] fix: updates to currency examples

---
 .examples/currency/currency-default.vue       | 6 +++++-
 .examples/currency/currency-props-explore.vue | 1 +
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/.examples/currency/currency-default.vue b/.examples/currency/currency-default.vue
index 80890c30..f960ada3 100644
--- a/.examples/currency/currency-default.vue
+++ b/.examples/currency/currency-default.vue
@@ -10,7 +10,11 @@ const value = ref(false)
   -->
   <FormKit type="form" #default="{ value }" :actions="false">
     <!-- %partial%::html:: -->
-    <FormKit type="currency" name="currency" />
+    <FormKit
+      type="currency"
+      name="currency"
+      value="12345678.90"
+    />
     <!-- %partial%::html:: -->
     <pre wrap>{{ value }}</pre>
   </FormKit>
diff --git a/.examples/currency/currency-props-explore.vue b/.examples/currency/currency-props-explore.vue
index 59fdac0b..02923306 100644
--- a/.examples/currency/currency-props-explore.vue
+++ b/.examples/currency/currency-props-explore.vue
@@ -20,6 +20,7 @@ const value = ref(false)
       displayLocale="en-US"
       decimals="4"
       minDecimals="2"
+      value="123.1234"
     />
     <!-- %partial%::html:: -->
     <pre wrap>{{ value }}</pre>

From 550fa3d6bf9efeafe6abf8bdfda103012de74c8b Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Thu, 25 Apr 2024 11:03:14 -0400
Subject: [PATCH 03/34] docs: adds examples for option groups

---
 .examples/_data/citiesByState.js              | 638 ++++++++++++++++++
 .../autocomplete-option-groups.vue            |  20 +
 .examples/dropdown/dropdown-option-groups.vue |  20 +
 .examples/taglist/taglist-option-groups.vue   |  19 +
 changelog-pro/68.v.0.123.0.md                 |  10 +-
 inputs/autocomplete.md                        | 129 +++-
 inputs/dropdown.md                            | 124 +++-
 inputs/taglist.md                             | 239 +++++++
 8 files changed, 1173 insertions(+), 26 deletions(-)
 create mode 100644 .examples/_data/citiesByState.js
 create mode 100644 .examples/autocomplete-pro/autocomplete-option-groups.vue
 create mode 100644 .examples/dropdown/dropdown-option-groups.vue
 create mode 100644 .examples/taglist/taglist-option-groups.vue

diff --git a/.examples/_data/citiesByState.js b/.examples/_data/citiesByState.js
new file mode 100644
index 00000000..2d11b112
--- /dev/null
+++ b/.examples/_data/citiesByState.js
@@ -0,0 +1,638 @@
+export default [
+  {
+    group: 'Alabama',
+    options: [
+      { label: 'Birmingham', population: 209880, value: 'Birmingham, Alabama' },
+      { label: 'Montgomery', population: 198218, value: 'Montgomery, Alabama' },
+      { label: 'Mobile', population: 189572, value: 'Mobile, Alabama' },
+    ],
+  },
+  {
+    group: 'Alaska',
+    options: [
+      { label: 'Anchorage', population: 291247, value: 'Anchorage, Alaska' },
+      { label: 'Fairbanks', population: 31516, value: 'Fairbanks, Alaska' },
+      { label: 'Juneau', population: 32113, value: 'Juneau, Alaska' },
+    ],
+  },
+  {
+    group: 'Arizona',
+    options: [
+      { label: 'Phoenix', population: 1445632, value: 'Phoenix, Arizona' },
+      { label: 'Tucson', population: 548073, value: 'Tucson, Arizona' },
+      { label: 'Mesa', population: 518012, value: 'Mesa, Arizona' },
+    ],
+  },
+  {
+    group: 'Arkansas',
+    options: [
+      {
+        label: 'Little Rock',
+        population: 197312,
+        value: 'Little Rock, Arkansas',
+      },
+      { label: 'Fort Smith', population: 87818, value: 'Fort Smith, Arkansas' },
+      {
+        label: 'Fayetteville',
+        population: 87016,
+        value: 'Fayetteville, Arkansas',
+      },
+    ],
+  },
+  {
+    group: 'California',
+    options: [
+      {
+        label: 'Los Angeles',
+        population: 3976322,
+        value: 'Los Angeles, California',
+      },
+      {
+        label: 'San Diego',
+        population: 1394928,
+        value: 'San Diego, California',
+      },
+      { label: 'San Jose', population: 1026654, value: 'San Jose, California' },
+    ],
+  },
+  {
+    group: 'Colorado',
+    options: [
+      { label: 'Denver', population: 693060, value: 'Denver, Colorado' },
+      {
+        label: 'Colorado Springs',
+        population: 478221,
+        value: 'Colorado Springs, Colorado',
+      },
+      { label: 'Aurora', population: 366623, value: 'Aurora, Colorado' },
+    ],
+  },
+  {
+    group: 'Connecticut',
+    options: [
+      {
+        label: 'Bridgeport',
+        population: 148654,
+        value: 'Bridgeport, Connecticut',
+      },
+      {
+        label: 'New Haven',
+        population: 130250,
+        value: 'New Haven, Connecticut',
+      },
+      { label: 'Hartford', population: 123243, value: 'Hartford, Connecticut' },
+    ],
+  },
+  {
+    group: 'Delaware',
+    options: [
+      { label: 'Wilmington', population: 70676, value: 'Wilmington, Delaware' },
+      { label: 'Dover', population: 38458, value: 'Dover, Delaware' },
+      { label: 'Newark', population: 33387, value: 'Newark, Delaware' },
+    ],
+  },
+  {
+    group: 'Florida',
+    options: [
+      {
+        label: 'Jacksonville',
+        population: 892062,
+        value: 'Jacksonville, Florida',
+      },
+      { label: 'Miami', population: 470914, value: 'Miami, Florida' },
+      { label: 'Tampa', population: 399700, value: 'Tampa, Florida' },
+    ],
+  },
+  {
+    group: 'Georgia',
+    options: [
+      { label: 'Atlanta', population: 498044, value: 'Atlanta, Georgia' },
+      { label: 'Augusta', population: 197166, value: 'Augusta, Georgia' },
+      { label: 'Columbus', population: 195769, value: 'Columbus, Georgia' },
+    ],
+  },
+  {
+    group: 'Hawaii',
+    options: [
+      { label: 'Honolulu', population: 374658, value: 'Honolulu, Hawaii' },
+      {
+        label: 'East Honolulu',
+        population: 49105,
+        value: 'East Honolulu, Hawaii',
+      },
+      { label: 'Pearl City', population: 47698, value: 'Pearl City, Hawaii' },
+    ],
+  },
+  {
+    group: 'Idaho',
+    options: [
+      { label: 'Boise', population: 228959, value: 'Boise, Idaho' },
+      { label: 'Meridian', population: 106804, value: 'Meridian, Idaho' },
+      { label: 'Nampa', population: 106475, value: 'Nampa, Idaho' },
+    ],
+  },
+  {
+    group: 'Illinois',
+    options: [
+      { label: 'Chicago', population: 2705994, value: 'Chicago, Illinois' },
+      { label: 'Aurora', population: 199602, value: 'Aurora, Illinois' },
+      { label: 'Rockford', population: 147051, value: 'Rockford, Illinois' },
+    ],
+  },
+  {
+    group: 'Indiana',
+    options: [
+      {
+        label: 'Indianapolis',
+        population: 867125,
+        value: 'Indianapolis, Indiana',
+      },
+      { label: 'Fort Wayne', population: 270402, value: 'Fort Wayne, Indiana' },
+      { label: 'Evansville', population: 118930, value: 'Evansville, Indiana' },
+    ],
+  },
+  {
+    group: 'Iowa',
+    options: [
+      { label: 'Des Moines', population: 214778, value: 'Des Moines, Iowa' },
+      {
+        label: 'Cedar Rapids',
+        population: 132228,
+        value: 'Cedar Rapids, Iowa',
+      },
+      { label: 'Davenport', population: 101532, value: 'Davenport, Iowa' },
+    ],
+  },
+  {
+    group: 'Kansas',
+    options: [
+      { label: 'Wichita', population: 389938, value: 'Wichita, Kansas' },
+      {
+        label: 'Overland Park',
+        population: 195494,
+        value: 'Overland Park, Kansas',
+      },
+      {
+        label: 'Kansas City',
+        population: 152960,
+        value: 'Kansas City, Kansas',
+      },
+    ],
+  },
+  {
+    group: 'Kentucky',
+    options: [
+      {
+        label: 'Louisville',
+        population: 615366,
+        value: 'Louisville, Kentucky',
+      },
+      { label: 'Lexington', population: 314488, value: 'Lexington, Kentucky' },
+      {
+        label: 'Bowling Green',
+        population: 70846,
+        value: 'Bowling Green, Kentucky',
+      },
+    ],
+  },
+  {
+    group: 'Louisiana',
+    options: [
+      {
+        label: 'New Orleans',
+        population: 393292,
+        value: 'New Orleans, Louisiana',
+      },
+      {
+        label: 'Baton Rouge',
+        population: 227715,
+        value: 'Baton Rouge, Louisiana',
+      },
+      {
+        label: 'Shreveport',
+        population: 194920,
+        value: 'Shreveport, Louisiana',
+      },
+    ],
+  },
+  {
+    group: 'Maine',
+    options: [
+      { label: 'Portland', population: 66591, value: 'Portland, Maine' },
+      { label: 'Lewiston', population: 36136, value: 'Lewiston, Maine' },
+      { label: 'Bangor', population: 31666, value: 'Bangor, Maine' },
+    ],
+  },
+  {
+    group: 'Maryland',
+    options: [
+      { label: 'Baltimore', population: 611648, value: 'Baltimore, Maryland' },
+      { label: 'Columbia', population: 105162, value: 'Columbia, Maryland' },
+      { label: 'Germantown', population: 90601, value: 'Germantown, Maryland' },
+    ],
+  },
+  {
+    group: 'Massachusetts',
+    options: [
+      { label: 'Boston', population: 694583, value: 'Boston, Massachusetts' },
+      {
+        label: 'Worcester',
+        population: 185877,
+        value: 'Worcester, Massachusetts',
+      },
+      {
+        label: 'Springfield',
+        population: 154341,
+        value: 'Springfield, Massachusetts',
+      },
+    ],
+  },
+  {
+    group: 'Michigan',
+    options: [
+      { label: 'Detroit', population: 673104, value: 'Detroit, Michigan' },
+      {
+        label: 'Grand Rapids',
+        population: 200217,
+        value: 'Grand Rapids, Michigan',
+      },
+      { label: 'Warren', population: 134587, value: 'Warren, Michigan' },
+    ],
+  },
+  {
+    group: 'Minnesota',
+    options: [
+      {
+        label: 'Minneapolis',
+        population: 422331,
+        value: 'Minneapolis, Minnesota',
+      },
+      {
+        label: 'Saint Paul',
+        population: 306621,
+        value: 'Saint Paul, Minnesota',
+      },
+      { label: 'Rochester', population: 118935, value: 'Rochester, Minnesota' },
+    ],
+  },
+  {
+    group: 'Mississippi',
+    options: [
+      { label: 'Jackson', population: 153701, value: 'Jackson, Mississippi' },
+      { label: 'Gulfport', population: 71496, value: 'Gulfport, Mississippi' },
+      {
+        label: 'Southaven',
+        population: 54418,
+        value: 'Southaven, Mississippi',
+      },
+    ],
+  },
+  {
+    group: 'Missouri',
+    options: [
+      {
+        label: 'Kansas City',
+        population: 488943,
+        value: 'Kansas City, Missouri',
+      },
+      {
+        label: 'Saint Louis',
+        population: 302838,
+        value: 'Saint Louis, Missouri',
+      },
+      {
+        label: 'Springfield',
+        population: 167376,
+        value: 'Springfield, Missouri',
+      },
+    ],
+  },
+  {
+    group: 'Montana',
+    options: [
+      { label: 'Billings', population: 110263, value: 'Billings, Montana' },
+      { label: 'Missoula', population: 74727, value: 'Missoula, Montana' },
+      {
+        label: 'Great Falls',
+        population: 58402,
+        value: 'Great Falls, Montana',
+      },
+    ],
+  },
+  {
+    group: 'Nebraska',
+    options: [
+      { label: 'Omaha', population: 478192, value: 'Omaha, Nebraska' },
+      { label: 'Lincoln', population: 287401, value: 'Lincoln, Nebraska' },
+      { label: 'Bellevue', population: 54734, value: 'Bellevue, Nebraska' },
+    ],
+  },
+  {
+    group: 'Nevada',
+    options: [
+      { label: 'Las Vegas', population: 635628, value: 'Las Vegas, Nevada' },
+      { label: 'Henderson', population: 320189, value: 'Henderson, Nevada' },
+      { label: 'Reno', population: 255601, value: 'Reno, Nevada' },
+    ],
+  },
+  {
+    group: 'New Hampshire',
+    options: [
+      {
+        label: 'Manchester',
+        population: 112525,
+        value: 'Manchester, New Hampshire',
+      },
+      { label: 'Nashua', population: 89536, value: 'Nashua, New Hampshire' },
+      { label: 'Concord', population: 43172, value: 'Concord, New Hampshire' },
+    ],
+  },
+  {
+    group: 'New Jersey',
+    options: [
+      { label: 'Newark', population: 282011, value: 'Newark, New Jersey' },
+      {
+        label: 'Jersey City',
+        population: 265549,
+        value: 'Jersey City, New Jersey',
+      },
+      { label: 'Paterson', population: 145948, value: 'Paterson, New Jersey' },
+    ],
+  },
+  {
+    group: 'New Mexico',
+    options: [
+      {
+        label: 'Albuquerque',
+        population: 560218,
+        value: 'Albuquerque, New Mexico',
+      },
+      {
+        label: 'Las Cruces',
+        population: 102512,
+        value: 'Las Cruces, New Mexico',
+      },
+      {
+        label: 'Rio Rancho',
+        population: 99710,
+        value: 'Rio Rancho, New Mexico',
+      },
+    ],
+  },
+  {
+    group: 'New York',
+    options: [
+      {
+        label: 'New York City',
+        population: 8175133,
+        value: 'New York City, New York',
+      },
+      { label: 'Buffalo', population: 261310, value: 'Buffalo, New York' },
+      { label: 'Rochester', population: 210565, value: 'Rochester, New York' },
+    ],
+  },
+  {
+    group: 'North Carolina',
+    options: [
+      {
+        label: 'Charlotte',
+        population: 731424,
+        value: 'Charlotte, North Carolina',
+      },
+      {
+        label: 'Raleigh',
+        population: 474069,
+        value: 'Raleigh, North Carolina',
+      },
+      {
+        label: 'Greensboro',
+        population: 299035,
+        value: 'Greensboro, North Carolina',
+      },
+    ],
+  },
+  {
+    group: 'North Dakota',
+    options: [
+      { label: 'Fargo', population: 113658, value: 'Fargo, North Dakota' },
+      { label: 'Bismarck', population: 61272, value: 'Bismarck, North Dakota' },
+      {
+        label: 'Grand Forks',
+        population: 56791,
+        value: 'Grand Forks, North Dakota',
+      },
+    ],
+  },
+  {
+    group: 'Ohio',
+    options: [
+      { label: 'Columbus', population: 822553, value: 'Columbus, Ohio' },
+      { label: 'Cleveland', population: 396815, value: 'Cleveland, Ohio' },
+      { label: 'Cincinnati', population: 296943, value: 'Cincinnati, Ohio' },
+    ],
+  },
+  {
+    group: 'Oklahoma',
+    options: [
+      {
+        label: 'Oklahoma City',
+        population: 649021,
+        value: 'Oklahoma City, Oklahoma',
+      },
+      { label: 'Tulsa', population: 403505, value: 'Tulsa, Oklahoma' },
+      { label: 'Norman', population: 110925, value: 'Norman, Oklahoma' },
+    ],
+  },
+  {
+    group: 'Oregon',
+    options: [
+      { label: 'Portland', population: 647805, value: 'Portland, Oregon' },
+      { label: 'Salem', population: 154637, value: 'Salem, Oregon' },
+      { label: 'Eugene', population: 156185, value: 'Eugene, Oregon' },
+    ],
+  },
+  {
+    group: 'Pennsylvania',
+    options: [
+      {
+        label: 'Philadelphia',
+        population: 1584138,
+        value: 'Philadelphia, Pennsylvania',
+      },
+      {
+        label: 'Pittsburgh',
+        population: 303625,
+        value: 'Pittsburgh, Pennsylvania',
+      },
+      {
+        label: 'Allentown',
+        population: 120207,
+        value: 'Allentown, Pennsylvania',
+      },
+    ],
+  },
+  {
+    group: 'Rhode Island',
+    options: [
+      {
+        label: 'Providence',
+        population: 179883,
+        value: 'Providence, Rhode Island',
+      },
+      { label: 'Warwick', population: 82039, value: 'Warwick, Rhode Island' },
+      { label: 'Cranston', population: 80566, value: 'Cranston, Rhode Island' },
+    ],
+  },
+  {
+    group: 'South Carolina',
+    options: [
+      {
+        label: 'Charleston',
+        population: 130113,
+        value: 'Charleston, South Carolina',
+      },
+      {
+        label: 'Columbia',
+        population: 129272,
+        value: 'Columbia, South Carolina',
+      },
+      {
+        label: 'North Charleston',
+        population: 115382,
+        value: 'North Charleston, South Carolina',
+      },
+    ],
+  },
+  {
+    group: 'South Dakota',
+    options: [
+      {
+        label: 'Sioux Falls',
+        population: 153888,
+        value: 'Sioux Falls, South Dakota',
+      },
+      {
+        label: 'Rapid City',
+        population: 69030,
+        value: 'Rapid City, South Dakota',
+      },
+      { label: 'Aberdeen', population: 28489, value: 'Aberdeen, South Dakota' },
+    ],
+  },
+  {
+    group: 'Tennessee',
+    options: [
+      { label: 'Nashville', population: 689447, value: 'Nashville, Tennessee' },
+      { label: 'Memphis', population: 650618, value: 'Memphis, Tennessee' },
+      { label: 'Knoxville', population: 186239, value: 'Knoxville, Tennessee' },
+    ],
+  },
+  {
+    group: 'Texas',
+    options: [
+      { label: 'Houston', population: 2320268, value: 'Houston, Texas' },
+      {
+        label: 'San Antonio',
+        population: 1547253,
+        value: 'San Antonio, Texas',
+      },
+      { label: 'Dallas', population: 1317929, value: 'Dallas, Texas' },
+    ],
+  },
+  {
+    group: 'Utah',
+    options: [
+      {
+        label: 'Salt Lake City',
+        population: 200567,
+        value: 'Salt Lake City, Utah',
+      },
+      {
+        label: 'West Valley City',
+        population: 135248,
+        value: 'West Valley City, Utah',
+      },
+      { label: 'Provo', population: 115264, value: 'Provo, Utah' },
+    ],
+  },
+  {
+    group: 'Vermont',
+    options: [
+      { label: 'Burlington', population: 42284, value: 'Burlington, Vermont' },
+      {
+        label: 'South Burlington',
+        population: 18998,
+        value: 'South Burlington, Vermont',
+      },
+      { label: 'Essex', population: 21291, value: 'Essex, Vermont' },
+    ],
+  },
+  {
+    group: 'Virginia',
+    options: [
+      {
+        label: 'Virginia Beach',
+        population: 450435,
+        value: 'Virginia Beach, Virginia',
+      },
+      { label: 'Norfolk', population: 242742, value: 'Norfolk, Virginia' },
+      {
+        label: 'Chesapeake',
+        population: 240397,
+        value: 'Chesapeake, Virginia',
+      },
+    ],
+  },
+  {
+    group: 'Washington',
+    options: [
+      { label: 'Seattle', population: 744955, value: 'Seattle, Washington' },
+      { label: 'Spokane', population: 219190, value: 'Spokane, Washington' },
+      { label: 'Tacoma', population: 217827, value: 'Tacoma, Washington' },
+    ],
+  },
+  {
+    group: 'West Virginia',
+    options: [
+      {
+        label: 'Charleston',
+        population: 51400,
+        value: 'Charleston, West Virginia',
+      },
+      {
+        label: 'Huntington',
+        population: 46413,
+        value: 'Huntington, West Virginia',
+      },
+      {
+        label: 'Morgantown',
+        population: 30505,
+        value: 'Morgantown, West Virginia',
+      },
+    ],
+  },
+  {
+    group: 'Wisconsin',
+    options: [
+      { label: 'Milwaukee', population: 594833, value: 'Milwaukee, Wisconsin' },
+      { label: 'Madison', population: 233209, value: 'Madison, Wisconsin' },
+      { label: 'Green Bay', population: 104578, value: 'Green Bay, Wisconsin' },
+    ],
+  },
+  {
+    group: 'Wyoming',
+    options: [
+      { label: 'Cheyenne', population: 59466, value: 'Cheyenne, Wyoming' },
+      { label: 'Casper', population: 57913, value: 'Casper, Wyoming' },
+      { label: 'Laramie', population: 32959, value: 'Laramie, Wyoming' },
+    ],
+  },
+  {
+    value: 1,
+    label: '1',
+  },
+  {
+    value: 2,
+    label: '2',
+  },
+]
diff --git a/.examples/autocomplete-pro/autocomplete-option-groups.vue b/.examples/autocomplete-pro/autocomplete-option-groups.vue
new file mode 100644
index 00000000..e85eaa7b
--- /dev/null
+++ b/.examples/autocomplete-pro/autocomplete-option-groups.vue
@@ -0,0 +1,20 @@
+<script setup>
+import citiesByState from './citiesByState.js'
+</script>
+
+<template>
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <FormKit
+      type="autocomplete"
+      name="most_populous_cities"
+      label="Choose your favorite countries"
+      placeholder="New York, Los Angeles..."
+      :options="citiesByState"
+      multiple
+      popover
+    />
+    <pre wrap>{{ value }}</pre>
+  </FormKit>
+</template>
+
+<style></style>
diff --git a/.examples/dropdown/dropdown-option-groups.vue b/.examples/dropdown/dropdown-option-groups.vue
new file mode 100644
index 00000000..0eee1743
--- /dev/null
+++ b/.examples/dropdown/dropdown-option-groups.vue
@@ -0,0 +1,20 @@
+<script setup>
+import citiesByState from './citiesByState.js'
+</script>
+
+<template>
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <FormKit
+      type="dropdown"
+      name="most_populous_cities"
+      label="Choose your favorite countries"
+      placeholder="New York, Los Angeles..."
+      :options="citiesByState"
+      multiple
+      popover
+    />
+    <pre wrap>{{ value }}</pre>
+  </FormKit>
+</template>
+
+<style></style>
diff --git a/.examples/taglist/taglist-option-groups.vue b/.examples/taglist/taglist-option-groups.vue
new file mode 100644
index 00000000..fa9fd6c6
--- /dev/null
+++ b/.examples/taglist/taglist-option-groups.vue
@@ -0,0 +1,19 @@
+<script setup>
+import citiesByState from './citiesByState.js'
+</script>
+
+<template>
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <FormKit
+      type="taglist"
+      name="most_populous_cities"
+      label="Choose your favorite countries"
+      placeholder="New York, Los Angeles..."
+      :options="citiesByState"
+      multiple
+    />
+    <pre wrap>{{ value }}</pre>
+  </FormKit>
+</template>
+
+<style></style>
diff --git a/changelog-pro/68.v.0.123.0.md b/changelog-pro/68.v.0.123.0.md
index 7c1bd9e8..ed04db22 100644
--- a/changelog-pro/68.v.0.123.0.md
+++ b/changelog-pro/68.v.0.123.0.md
@@ -2,9 +2,15 @@
 
 ### April 25, 2024
 
-### ⚠️ Breaking Changes
+::Callout
+---
+type: "warning"
+name: "Breaking Changes"
+---
 
-- The rating input has been rewritten to be based on a radio group to provide better accessibility. While the API remains the same, be sure to update your theme at `themes.formkit.com`.
+The rating input has been rewritten to be based on a radio group to provide better accessibility. While the API remains the same, be sure to update your theme at `themes.formkit.com`.
+
+::
 
 ### 💪 New Features
 
diff --git a/inputs/autocomplete.md b/inputs/autocomplete.md
index 771c9365..57616adb 100644
--- a/inputs/autocomplete.md
+++ b/inputs/autocomplete.md
@@ -353,6 +353,21 @@ file: [
 ---
 ::
 
+## Option groups
+
+If you would like the listitems in the listbox to be grouped, pass the `options` prop an array of objects and include the property `group`:
+
+::Example
+---
+name: "Autocomplete"
+min-height: 550
+file: [
+  "_content/_examples/autocomplete-pro/autocomplete-option-groups.vue",
+  "_content/_examples/_data/citiesByState.js"
+]
+---
+::
+
 
 ## Full example
 
@@ -838,14 +853,12 @@ schema: [
 ---
 ::
 
-### Inner listbox structure
-
-Below is the inner options list (`listbox`) structure from the diagrams above:
+### Listbox structure
 
 ::FormKitInputDiagram
 ---
 hide-on-small: true
-class: "input-diagram--autocomplete"
+class: "input-diagram--dropdown"
 schema: [
   {
     name: "dropdownWrapper",
@@ -865,20 +878,108 @@ schema: [
             ]
           },
           {
-            name: "listitem",
-            class: "flex flex-grow",
-            position: "right",
+            name: "listitems",
+            children: [{
+              name: 'listitem',
+              class: "flex flex-grow",
+              position: "right",
+              children: [
+                {
+                  name: "selectedIcon",
+                  content: "✔️"
+                },
+                {
+                  name: "option",
+                  content: "Gray",
+                  position: "right",
+                  class: "flex flex-grow"
+                },
+              ]
+            }]
+          },
+          {
+            name: "loadMore",
             children: [
               {
-                name: "selectedIcon",
-                content: "✔️"
+                name: "loadMoreInner",
+                children: [
+                  {
+                    name: "loaderIcon",
+                    content: "⏳",
+                    class: "text-center"
+                  }
+                ]
               },
+            ]
+          },
+        ]
+      },
+    ]
+  }
+]
+---
+::
+
+### Grouped Listbox Structure
+
+::FormKitInputDiagram
+---
+hide-on-small: true
+class: "input-diagram--dropdown"
+schema: [
+  {
+    name: "dropdownWrapper",
+    position: "right",
+    children: [
+      {
+        name: "listbox",
+        position: "right",
+        children: [
+        {
+            name: "emptyMessage",
+            children: [
               {
-                name: "option",
-                content: "Serena",
-                position: "right",
-                class: "flex flex-grow"
-              },
+                name: "emptyMessageInner",
+                content: "No options to display.",
+              }
+            ]
+          },
+          {
+            name: "listitems",
+            children: [
+              {
+                name: 'listitemGroup',
+                children: [
+                  {
+                    name: 'groupLabel'
+                  },
+                  {
+                    name: 'groupList',
+                    children: [
+                      {
+                        name: 'innerListitems',
+                        children: [{
+                          name: 'listitem',
+                          class: "flex flex-grow",
+                          position: "right",
+                          children: [
+                            {
+                              name: "selectedIcon",
+                              content: "✔️"
+                            },
+                            {
+                              name: "option",
+                              content: "Gray",
+                              position: "right",
+                              class: "flex flex-grow"
+                            },
+                          ]
+                        }]
+                      }
+                    ]
+                  }
+                ]
+              }
             ]
           },
           {
diff --git a/inputs/dropdown.md b/inputs/dropdown.md
index 53a92ea5..ebc026f2 100644
--- a/inputs/dropdown.md
+++ b/inputs/dropdown.md
@@ -306,6 +306,22 @@ file: [
 ---
 ::
 
+## Option groups
+
+If you would like the listitems in the listbox to be grouped, pass the `options` prop an array of objects and include the property `group`:
+
+::Example
+---
+name: "Dropdown"
+min-height: 550
+file: [
+  "_content/_examples/dropdown/dropdown-option-groups.vue",
+  "_content/_examples/_data/citiesByState.js"
+]
+---
+::
+
+
 ## Props & Attributes
 
 ::ReferenceTable
@@ -538,20 +554,108 @@ schema: [
             ]
           },
           {
-            name: "listitem",
-            class: "flex flex-grow",
-            position: "right",
+            name: "listitems",
+            children: [{
+              name: 'listitem',
+              class: "flex flex-grow",
+              position: "right",
+              children: [
+                {
+                  name: "selectedIcon",
+                  content: "✔️"
+                },
+                {
+                  name: "option",
+                  content: "Gray",
+                  position: "right",
+                  class: "flex flex-grow"
+                },
+              ]
+            }]
+          },
+          {
+            name: "loadMore",
             children: [
               {
-                name: "selectedIcon",
-                content: "✔️"
+                name: "loadMoreInner",
+                children: [
+                  {
+                    name: "loaderIcon",
+                    content: "⏳",
+                    class: "text-center"
+                  }
+                ]
               },
+            ]
+          },
+        ]
+      },
+    ]
+  }
+]
+---
+::
+
+### Grouped Listbox Structure
+
+::FormKitInputDiagram
+---
+hide-on-small: true
+class: "input-diagram--dropdown"
+schema: [
+  {
+    name: "dropdownWrapper",
+    position: "right",
+    children: [
+      {
+        name: "listbox",
+        position: "right",
+        children: [
+        {
+            name: "emptyMessage",
+            children: [
               {
-                name: "option",
-                content: "Gray",
-                position: "right",
-                class: "flex flex-grow"
-              },
+                name: "emptyMessageInner",
+                content: "No options to display.",
+              }
+            ]
+          },
+          {
+            name: "listitems",
+            children: [
+              {
+                name: 'listitemGroup',
+                children: [
+                  {
+                    name: 'groupLabel'
+                  },
+                  {
+                    name: 'groupList',
+                    children: [
+                      {
+                        name: 'innerListitems',
+                        children: [{
+                          name: 'listitem',
+                          class: "flex flex-grow",
+                          position: "right",
+                          children: [
+                            {
+                              name: "selectedIcon",
+                              content: "✔️"
+                            },
+                            {
+                              name: "option",
+                              content: "Gray",
+                              position: "right",
+                              class: "flex flex-grow"
+                            },
+                          ]
+                        }]
+                      }
+                    ]
+                  }
+                ]
+              }
             ]
           },
           {
diff --git a/inputs/taglist.md b/inputs/taglist.md
index 1aa4afda..9cb4df61 100644
--- a/inputs/taglist.md
+++ b/inputs/taglist.md
@@ -266,6 +266,22 @@ file: [
 ---
 ::
 
+## Option groups
+
+If you would like the listitems in the listbox to be grouped, pass the `options` prop an array of objects and include the property `group`:
+
+::Example
+---
+name: "Taglist"
+min-height: 550
+file: [
+  "_content/_examples/taglist/taglist-option-groups.vue",
+  "_content/_examples/_data/citiesByState.js"
+]
+---
+::
+
+
 
 ## Full example
 
@@ -469,6 +485,229 @@ data: [
 ---
 ::
 
+## Sections
+
+:SectionKeysIntro
+
+### Listbox structure
+
+::FormKitInputDiagram
+---
+hide-on-small: true
+class: "input-diagram--dropdown"
+schema: [
+  {
+    name: "dropdownWrapper",
+    position: "right",
+    children: [
+      {
+        name: "listbox",
+        position: "right",
+        children: [
+        {
+            name: "emptyMessage",
+            children: [
+              {
+                name: "emptyMessageInner",
+                content: "No options to display.",
+              }
+            ]
+          },
+          {
+            name: "listitems",
+            children: [{
+              name: 'listitem',
+              class: "flex flex-grow",
+              position: "right",
+              children: [
+                {
+                  name: "selectedIcon",
+                  content: "✔️"
+                },
+                {
+                  name: "option",
+                  content: "Gray",
+                  position: "right",
+                  class: "flex flex-grow"
+                },
+              ]
+            }]
+          },
+          {
+            name: "loadMore",
+            children: [
+              {
+                name: "loadMoreInner",
+                children: [
+                  {
+                    name: "loaderIcon",
+                    content: "⏳",
+                    class: "text-center"
+                  }
+                ]
+              },
+            ]
+          },
+        ]
+      },
+    ]
+  }
+]
+---
+::
+
+### Grouped Listbox Structure
+
+::FormKitInputDiagram
+---
+hide-on-small: true
+class: "input-diagram--dropdown"
+schema: [
+  {
+    name: "dropdownWrapper",
+    position: "right",
+    children: [
+      {
+        name: "listbox",
+        position: "right",
+        children: [
+        {
+            name: "emptyMessage",
+            children: [
+              {
+                name: "emptyMessageInner",
+                content: "No options to display.",
+              }
+            ]
+          },
+          {
+            name: "listitems",
+            children: [
+              {
+                name: 'listitemGroup',
+                children: [
+                  {
+                    name: 'groupLabel'
+                  },
+                  {
+                    name: 'groupList',
+                    children: [
+                      {
+                        name: 'innerListitems',
+                        children: [{
+                          name: 'listitem',
+                          class: "flex flex-grow",
+                          position: "right",
+                          children: [
+                            {
+                              name: "selectedIcon",
+                              content: "✔️"
+                            },
+                            {
+                              name: "option",
+                              content: "Gray",
+                              position: "right",
+                              class: "flex flex-grow"
+                            },
+                          ]
+                        }]
+                      }
+                    ]
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            name: "loadMore",
+            children: [
+              {
+                name: "loadMoreInner",
+                children: [
+                  {
+                    name: "loaderIcon",
+                    content: "⏳",
+                    class: "text-center"
+                  }
+                ]
+              },
+            ]
+          },
+        ]
+      },
+    ]
+  }
+]
+---
+::
+
+#### Taglist selections
+
+::FormKitInputDiagram
+---
+hide-on-small: true
+class: "input-diagram--dropdown-outer"
+schema: [
+  {
+    name: "selector",
+    class: "flex flex-grow",
+    children: [
+      {
+        name: "tagsWrapper",
+        class: "flex flex-grow",
+        children: [
+          {
+            name: "tags",
+            class: "flex flex-grow border-solid",
+            children: [
+              {
+                name: "tagWrapper",
+                children: [
+                  {
+                    name: "tag",
+                    class: 'flex',
+                    children: [
+                      {
+                        name: "tagLabel",
+                        content: 'Gray'
+                      },
+                      {
+                        name: "removeSelection",
+                        content: '×'
+                      }
+                    ]
+                  },
+                ]
+              },
+              {
+                name: "tagWrapper",
+                children: [
+                  {
+                    name: "tag",
+                    class: 'flex',
+                    children: [
+                      {
+                        name: "tagLabel",
+                        content: 'Blue'
+                      },
+                      {
+                        name: "removeSelection",
+                        content: '×'
+                      }
+                    ]
+                  },
+                ]
+              }
+            ],
+          },
+        ]
+      },
+    ]
+  }
+]
+---
+::
+
 ## Accessibility
 
 All FormKit inputs are designed with the following accessibility considerations in mind. Help us continually improve accessibility for all by filing accessibility issues [here](https://github.com/formkit/formkit/issues/new?assignees=&labels=%F0%9F%90%9B+bug-report%2C%E2%9B%91+Needs+triage&projects=&template=bug-report.yml): 

From 4461b1fc4758ad80d7745d45bc12a20fe999c89a Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Thu, 25 Apr 2024 11:14:25 -0400
Subject: [PATCH 04/34] docs: removes ungrouped options from citiesByState

---
 .examples/_data/citiesByState.js | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/.examples/_data/citiesByState.js b/.examples/_data/citiesByState.js
index 2d11b112..55cb98c8 100644
--- a/.examples/_data/citiesByState.js
+++ b/.examples/_data/citiesByState.js
@@ -627,12 +627,4 @@ export default [
       { label: 'Laramie', population: 32959, value: 'Laramie, Wyoming' },
     ],
   },
-  {
-    value: 1,
-    label: '1',
-  },
-  {
-    value: 2,
-    label: '2',
-  },
 ]

From 20f225584bfa81f8fecbe2a319b452f0b7c2c21c Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Thu, 25 Apr 2024 13:48:10 -0400
Subject: [PATCH 05/34] docs: adds changelog for FormKit Pro v.0.123.1

---
 changelog-pro/69.v.0.123.1.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 changelog-pro/69.v.0.123.1.md

diff --git a/changelog-pro/69.v.0.123.1.md b/changelog-pro/69.v.0.123.1.md
new file mode 100644
index 00000000..11c23df5
--- /dev/null
+++ b/changelog-pro/69.v.0.123.1.md
@@ -0,0 +1,8 @@
+## 0.123.1
+
+### April 25, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue with `autocomplete` and `taglist` inputs where cloning during search prevented lookup of values with pojos.
+

From 76c247883cb686122b36c0847b12499abe1b35aa Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Fri, 26 Apr 2024 09:59:57 -0400
Subject: [PATCH 06/34] docs: Adds changelog for FormKit Pro v0.123.2

---
 changelog-pro/70.v.0.123.2.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/70.v.0.123.2.md

diff --git a/changelog-pro/70.v.0.123.2.md b/changelog-pro/70.v.0.123.2.md
new file mode 100644
index 00000000..14ee125a
--- /dev/null
+++ b/changelog-pro/70.v.0.123.2.md
@@ -0,0 +1,7 @@
+## 0.123.2
+
+### April 26, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue [#1335](https://github.com/formkit/formkit/issues/1335) where the `options` prop typings for dropdown family inputs were incorrect.

From c920369cb378d3342a8a53551b063f84def7eecc Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Fri, 26 Apr 2024 12:10:54 -0400
Subject: [PATCH 07/34] docs: adds changelog for FormKit Pro v0.123.3

---
 changelog-pro/71.v.0.123.3.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/71.v.0.123.3.md

diff --git a/changelog-pro/71.v.0.123.3.md b/changelog-pro/71.v.0.123.3.md
new file mode 100644
index 00000000..a91a05f9
--- /dev/null
+++ b/changelog-pro/71.v.0.123.3.md
@@ -0,0 +1,7 @@
+## 0.123.3
+
+### April 26, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue where filtering option groups were not being filtered down via search to individual listitem.

From bcc828bd22c75b98fd28112f92a1dd69e941a841 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Fri, 26 Apr 2024 15:41:05 -0400
Subject: [PATCH 08/34] docs: adds changelog for FormKit Pro v0.123.4

---
 changelog-pro/72.v.0.123.4.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/72.v.0.123.4.md

diff --git a/changelog-pro/72.v.0.123.4.md b/changelog-pro/72.v.0.123.4.md
new file mode 100644
index 00000000..9829a932
--- /dev/null
+++ b/changelog-pro/72.v.0.123.4.md
@@ -0,0 +1,7 @@
+## 0.123.4
+
+### April 26, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue where attempting to deselect a list item from the dropdown family inputs with a value of pojo was not working as expected.

From 52d8bceab94663db2c8a36d748da06e300349a24 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Fri, 26 Apr 2024 17:37:48 -0400
Subject: [PATCH 09/34] docs: Adds changelog for FormKit Pro v0.123.5

---
 changelog-pro/73.v.0.123.5.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 changelog-pro/73.v.0.123.5.md

diff --git a/changelog-pro/73.v.0.123.5.md b/changelog-pro/73.v.0.123.5.md
new file mode 100644
index 00000000..22beb265
--- /dev/null
+++ b/changelog-pro/73.v.0.123.5.md
@@ -0,0 +1,13 @@
+## 0.123.5
+
+### April 26, 2024
+
+### 🐛 Bug fixes
+
+- Fixes dropdown family issue where the loading state of all selections would end at the same time, even if their await times were different because the values were pojos.
+
+- Fixes dropdown family issue where value of pojo would sometimes cause issues with setting the active descendant.
+
+- Fixes dropdown family where active selection via. keyhandlers on taglist tags was not working properly.
+
+- Prevents focus state of tag via. keydown if text input is present.

From b4cf017f531201391b5490067b0564cd34957e1d Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Sat, 27 Apr 2024 12:41:00 -0400
Subject: [PATCH 10/34] docs: adds changelog for FormKit Pro v0.123.6

---
 changelog-pro/74.v.0.123.6.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/74.v.0.123.6.md

diff --git a/changelog-pro/74.v.0.123.6.md b/changelog-pro/74.v.0.123.6.md
new file mode 100644
index 00000000..5d3d2566
--- /dev/null
+++ b/changelog-pro/74.v.0.123.6.md
@@ -0,0 +1,7 @@
+## 0.123.6
+
+### April 27, 2024
+
+### 🐛 Bug fixes
+
+- Fixes dropdown family issue where hydration mismatch occurs when loading option with value of pojo that can't be reduced to a string as temporary label.

From 7d1c21f141abcbf9a44c6e25e3321e2d25f0f324 Mon Sep 17 00:00:00 2001
From: Chris Ellinger <cellinger@wearebraid.com>
Date: Wed, 1 May 2024 10:51:00 -0400
Subject: [PATCH 11/34] docs: adds new bronze sponsor logo

---
 getting-started/community.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/getting-started/community.md b/getting-started/community.md
index 4f31b57b..6500ca6c 100644
--- a/getting-started/community.md
+++ b/getting-started/community.md
@@ -75,6 +75,15 @@ Community involvement and contributions are one of the most important aspects of
         class="docs-partner"
         src="https://cdn.formk.it/web-assets/sponsors/zammad_logo-transparent.png"
         alt="PerByte logo"
+        style="display:inline-block;vertical-align: middle;width: 60px;margin-right: 25px;"
+    />
+</a>
+
+<a class="no-underline" href="https://wedgworth.com?utm_source=formkit&utm_medium=web">
+    <img
+        class="docs-partner"
+        src="https://cdn.formk.it/web-assets/sponsors/bronze-sponsor_wedgworth.png"
+        alt="Wedgworth's Inc logo"
         style="display:inline-block;vertical-align: middle;width: 120px;margin-right: 25px;"
     />
 </a>

From a5621db4e7721e97c92ea8e56fb909fe1abaef4f Mon Sep 17 00:00:00 2001
From: Chris Ellinger <cellinger@wearebraid.com>
Date: Wed, 1 May 2024 11:08:30 -0400
Subject: [PATCH 12/34] docs: correct resizing placed on wrong logo

---
 getting-started/community.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/getting-started/community.md b/getting-started/community.md
index 6500ca6c..b7d1310c 100644
--- a/getting-started/community.md
+++ b/getting-started/community.md
@@ -75,7 +75,7 @@ Community involvement and contributions are one of the most important aspects of
         class="docs-partner"
         src="https://cdn.formk.it/web-assets/sponsors/zammad_logo-transparent.png"
         alt="PerByte logo"
-        style="display:inline-block;vertical-align: middle;width: 60px;margin-right: 25px;"
+        style="display:inline-block;vertical-align: middle;width: 120px;margin-right: 25px;"
     />
 </a>
 
@@ -84,7 +84,7 @@ Community involvement and contributions are one of the most important aspects of
         class="docs-partner"
         src="https://cdn.formk.it/web-assets/sponsors/bronze-sponsor_wedgworth.png"
         alt="Wedgworth's Inc logo"
-        style="display:inline-block;vertical-align: middle;width: 120px;margin-right: 25px;"
+        style="display:inline-block;vertical-align: middle;width: 60px;margin-right: 25px;"
     />
 </a>
 

From 8d812e0434f636d90f1926b7cde302acecb27e9d Mon Sep 17 00:00:00 2001
From: Chris Ellinger <cellinger@wearebraid.com>
Date: Thu, 2 May 2024 16:32:48 -0400
Subject: [PATCH 13/34] docs:removes old sponsors from community page

---
 getting-started/community.md | 20 +-------------------
 1 file changed, 1 insertion(+), 19 deletions(-)

diff --git a/getting-started/community.md b/getting-started/community.md
index b7d1310c..5194bd87 100644
--- a/getting-started/community.md
+++ b/getting-started/community.md
@@ -39,25 +39,7 @@ Community involvement and contributions are one of the most important aspects of
     />
 </a>
 
-### Silver sponsors
-
-<a class="no-underline" href="https://www.peakcrypto.com?utm_source=formkit&utm_medium=web">
-    <img
-        class="docs-partner"
-        src="https://cdn.formk.it/web-assets/sponsors/peak-crypto.svg"
-        alt="Peak Crypto logo"
-        style="display:inline-block;vertical-align: middle;width: 135px;margin-right: 25px;margin-top: 10px;"
-    />
-</a>
-
-<a class="no-underline" href="https://surveyjs.io?utm_source=formkit&utm_medium=web">
-    <img
-        class="docs-partner"
-        src="https://cdn.formk.it/web-assets/sponsors/surveyjs.svg"
-        alt="SurveyJS logo"
-        style="display:inline-block;vertical-align: middle;width: 115px;margin-right: 25px;margin-top: 15px;"
-    />
-</a>
+<!-- ### Silver sponsors -->
 
 ### Bronze sponsors
 

From cc1ddbdc18b58f60e866d55fce84d419b5b8e4a1 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Mon, 6 May 2024 10:32:10 -0400
Subject: [PATCH 14/34] docs: removes unit docs for now

---
 inputs/unit.md | 144 -------------------------------------------------
 1 file changed, 144 deletions(-)
 delete mode 100644 inputs/unit.md

diff --git a/inputs/unit.md b/inputs/unit.md
deleted file mode 100644
index 3ae6b391..00000000
--- a/inputs/unit.md
+++ /dev/null
@@ -1,144 +0,0 @@
----
-title: Unit
-description: The unit input is used to create locale/currency specific parsed content for percentages, temperatures and measurements
----
-
-::InputPageHero
----
-type: "Unit"
----
-::
-
-:PageToc
-
-:ProInstallSnippet
-
-## Unit Input
-
-The unit input is used to create locale/currency specific parsed content for percentages, temperatures and measurements
-
-::Example
----
-name: "Unit input defaults"
-file: "_content/_examples/unit/unit-default.vue"
----
-::
-
-## Props
-
-### Unit
-
-The `unit` prop is the type of unit you want to display from percentages, temperatures, measurements, etc. A full list of allowed unit types are listed below:
-
-::ColumnList
----
-listItems: ['acre', 'bit', 'byte', 'celsius', 'centimeter', 'day', 'degree', 'fahrenheit', 'fluid-ounce', 'foot', 'gallon', 'gigabit', 'gigabyte', 'gram', 'hectare', 'hour', 'inch', 'kilobit', 'kilobyte', 'kilogram', 'kilometer', 'liter', 'megabit', 'megabyte', 'meter', 'microsecond', 'mile', 'mile-scandinavian', 'milliliter', 'millimeter', 'millisecond', 'minute', 'month', 'nanosecond', 'ounce', 'percent', 'petabyte', 'pound', 'second', 'stone', 'terabit', 'terabyte', 'week', 'yard', 'year']
----
-::
-
-::Example
----
-name: "Unit type examples"
-file: "_content/_examples/unit/unit-type-switcher.vue"
----
-::
-
-### Locale
-
-By default the locale will use what you have set in your `formkit.config.ts` as the desired locale. However you can override this with the `displayLocale` prop. For example, `en-US`, `de-DE`, `en-IN`, `zh-CN`, etc, etc.
-
-## Unit Additional Props
-
-### Decimals
-
-By default the decimals will display when the value contains the unit/locale decimal separator and will show default formatting decimal places to display for the given unit, however you can override this. By setting `decimals` to `false` or `0`, the value will not allow decimals or setting decimals to a numeric value will limit the maximum decimal places to that value.
-
-You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, you always want to show 2 decimal places you would set `minDecimals="2"`.
-
-### Minimum and Maximum Values
-
-Similar to a number input, you can set a `min` and `max` value.
-
-### Step
-
-Again, similar to a number input you can use the up/down keys to step the value. By default the step is `1` but you can override that with this prop.
-
-### Value Formatting
-
-Default value output is the value as a string to reduce issues with large number enumertation issues. However you can format the value as a string and include the currency symbol, grouping, decimal, etc as it is shown in the input.
-
-## Props & Attributes
-
-::ReferenceTable
----
-input: "unit" 
-data: [
-  {
-    prop: "unit",
-    type: "string",
-    default: "percent",
-    description: "Set the specified unit to use for this input"
-  },
-  {
-    prop: "displayLocale",
-    type: "string",
-    default: "en-US",
-    description: "Set the desired display locale to use for this input"
-  },
-  {
-    prop: "decimals",
-    type: "boolean|number",
-    default: "null",
-    description: "Choose to either completely disallow decimals or override the maximum number of decimals for the input"
-  },
-  {
-    prop: "minDecimals",
-    type: "number",
-    default: "null",
-    description: "Choose to show a minimum number of decimals should your input require this"
-  },
-  {
-    prop: "min",
-    type: "number",
-    default: "null",
-    description: "Minimum numeric value allowed. If zero or above, negatives will not be allowed"
-  },
-  {
-    prop: "max",
-    type: "number",
-    default: "null",
-    description: "Maximum numeric value allowed for this input"
-  },
-  {
-    prop: "step",
-    type: "number",
-    default: "1",
-    description: "When using the up/down keys, how much to modify the current value."
-  },
-  {
-    prop: "valueFormat",
-    type: "string",
-    default: "number",
-    description: "Choose between <code>number</code> and <code>string</code> whether you want a numeric value or a parsed string value"
-  },
-]
----
-::
-
-
-## Sections
-
-:SectionKeysIntro
-
-### Unit input diagram
-
-::FormKitInputDiagram
----
-prefix-icon-content: ""
-suffix-icon-content: ""
-label-content: "Unit Input"
-input-content: "1,234.56%"
-help-content: "Help text goes here"
-message-content: "Any messages would appear here"
----
-::

From 08f5c98c873b98f18a380f1d32f589913274145a Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Tue, 7 May 2024 08:33:55 -0400
Subject: [PATCH 15/34] docs: updates currency docs

---
 inputs/currency.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/inputs/currency.md b/inputs/currency.md
index aad212a1..b2a0fdd8 100644
--- a/inputs/currency.md
+++ b/inputs/currency.md
@@ -28,7 +28,7 @@ file: "_content/_examples/currency/currency-default.vue"
 
 ### Currency
 
-The `currency` prop is the three letter currency code and sets the proper formatting for the specified currency and also sets default decimal places for that currency. For a full list of supported currency types check: https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes
+The `currency` prop is the three letter currency code and sets the proper formatting for the specified currency. For a full list of supported currency types check: https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes
 
 ### Locale
 

From 675832ae2b027ae9c585cee609258dd8627f5e16 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Tue, 7 May 2024 09:47:55 -0400
Subject: [PATCH 16/34] docs: updates currency docs

---
 inputs/currency.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/inputs/currency.md b/inputs/currency.md
index b2a0fdd8..b526e832 100644
--- a/inputs/currency.md
+++ b/inputs/currency.md
@@ -46,9 +46,9 @@ file: "_content/_examples/currency/currency-simple-locale.vue"
 
 ### Decimals
 
-By default the decimals will display when the value contains the currency/locale decimal separator and will automatically know how many decimal places to display for the given currency, however you can override this. By setting `decimals` to `false` or `0`, the value will not allow decimals.
+By default the decimals will display when the value contains the currency/locale decimal separator and will automatically know how many decimal places to display for the given currency. If you would like to prevent decimals from being displayed, set `decimals` to `false` or `0`, the value will not allow decimals.
 
-You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, you always want to show 2 decimal places you would set `minDecimals="2"`.
+You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, setting the prop `minDecimals="2"` to will always show 2 decimal points.
 
 ### Minimum and Maximum Values
 

From d4ffaac356dd5d72c085c5279df504955986e226 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Tue, 7 May 2024 09:53:38 -0400
Subject: [PATCH 17/34] docs:

updates currency docs again
---
 inputs/currency.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/inputs/currency.md b/inputs/currency.md
index b526e832..ee36231d 100644
--- a/inputs/currency.md
+++ b/inputs/currency.md
@@ -48,7 +48,7 @@ file: "_content/_examples/currency/currency-simple-locale.vue"
 
 By default the decimals will display when the value contains the currency/locale decimal separator and will automatically know how many decimal places to display for the given currency. If you would like to prevent decimals from being displayed, set `decimals` to `false` or `0`, the value will not allow decimals.
 
-You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, setting the prop `minDecimals="2"` to will always show 2 decimal points.
+You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, setting the prop `minDecimals="2"` will always show 2 decimal points.
 
 ### Minimum and Maximum Values
 

From 760b7b0477337302ec51eaecadd1ea1783e77663 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Tue, 7 May 2024 11:11:14 -0400
Subject: [PATCH 18/34] docs: updates currency docs, adds changelog for FormKit
 Pro v0.124.0

---
 .examples/currency/currency-simple-locale.vue |  8 ++++----
 changelog-pro/75.v.0.124.0.md                 |  7 +++++++
 inputs/currency.md                            | 18 +++++++-----------
 3 files changed, 18 insertions(+), 15 deletions(-)
 create mode 100644 changelog-pro/75.v.0.124.0.md

diff --git a/.examples/currency/currency-simple-locale.vue b/.examples/currency/currency-simple-locale.vue
index 70b238b5..15fecbe3 100644
--- a/.examples/currency/currency-simple-locale.vue
+++ b/.examples/currency/currency-simple-locale.vue
@@ -13,7 +13,7 @@ const value = ref(false)
     <FormKit
       type="currency"
       currency="USD"
-      displayLocale="en-US"
+      display-locale="en"
       name="usd"
       value="12345678.90"
     />
@@ -21,7 +21,7 @@ const value = ref(false)
     <FormKit
       type="currency"
       currency="EUR"
-      displayLocale="de-DE"
+      display-locale="de"
       name="eur"
       value="12345678.90"
     />
@@ -29,7 +29,7 @@ const value = ref(false)
     <FormKit
       type="currency"
       currency="INR"
-      displayLocale="en-IN"
+      display-locale="en-IN"
       name="inr"
       value="12345678.90"
     />
@@ -37,7 +37,7 @@ const value = ref(false)
     <FormKit
       type="currency"
       currency="CNY"
-      displayLocale="zh-CN"
+      display-locale="zh-CN"
       name="cny"
       value="12345678.90"
     />
diff --git a/changelog-pro/75.v.0.124.0.md b/changelog-pro/75.v.0.124.0.md
new file mode 100644
index 00000000..17e4d977
--- /dev/null
+++ b/changelog-pro/75.v.0.124.0.md
@@ -0,0 +1,7 @@
+## 0.124.0
+
+### May 7, 2024
+
+### 💪 New features
+
+- Adds [`currency` input](/inputs/currency).
diff --git a/inputs/currency.md b/inputs/currency.md
index ee36231d..83a93483 100644
--- a/inputs/currency.md
+++ b/inputs/currency.md
@@ -13,9 +13,9 @@ type: "Currency"
 
 :ProInstallSnippet
 
-## Currency Input
+## Basic example
 
-The currency input is used to create locale/currency specific parsed content
+The `currency` input allows for restricted input of values based on the provided currency and locale.
 
 ::Example
 ---
@@ -32,7 +32,7 @@ The `currency` prop is the three letter currency code and sets the proper format
 
 ### Locale
 
-By default the locale will use what you have set in your `formkit.config.ts` as the desired locale. However you can override this with the `displayLocale` prop. For example, `en-US`, `de-DE`, `en-IN`, `zh-CN`, etc, etc.
+By default, the locale used will be that of what is set in your `formkit.config.ts`. This can be overriden with the `display-locale` prop. For example, `en`, `de`, `en-IN`, `zh-CN`, etc, etc.
 
 
 ::Example
@@ -46,21 +46,17 @@ file: "_content/_examples/currency/currency-simple-locale.vue"
 
 ### Decimals
 
-By default the decimals will display when the value contains the currency/locale decimal separator and will automatically know how many decimal places to display for the given currency. If you would like to prevent decimals from being displayed, set `decimals` to `false` or `0`, the value will not allow decimals.
+If you would like to prevent decimals from being displayed, set `decimals` to `false` or `0`.
 
-You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, setting the prop `minDecimals="2"` will always show 2 decimal points.
+You can also choose to set a minimum number of decimals with the `min-decimals` prop. For example, setting the prop `min-decimals="2"` will always show 2 decimal points.
 
 ### Minimum and Maximum Values
 
-Similar to a number input, you can set a `min` and `max` value.
+Setting the props `min` or `max` will prevent entry of a higher or lower value.
 
 ### Step
 
-Again, similar to a number input you can use the up/down keys to step the value. By default the step is `1` but you can override that with this prop.
-
-### Value Formatting
-
-Default value output is the value as a string to reduce issues with large number enumertation issues. However you can format the value as a string and include the currency symbol, grouping, decimal, etc as it is shown in the input.
+Value scan be incremented and decremented by use of the up/down keys. The degree by which the value changes is determined by the `step` prop.
 
 ::Example
 ---

From 2652ef8a223f1375904fb68dbfdc46ca63fd668e Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Tue, 7 May 2024 11:35:24 -0400
Subject: [PATCH 19/34] docs: removes currency example from docs

---
 essentials/examples.md | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/essentials/examples.md b/essentials/examples.md
index 67cb3923..3108381a 100644
--- a/essentials/examples.md
+++ b/essentials/examples.md
@@ -145,14 +145,6 @@ title: "Number input with custom step buttons"
 A custom input with +1 and -1 step buttons. Made using <code>createInput()</code>.
 ::
 
-::ExampleCard
----
-href: "https://formkit.link/68e51abc7431687edc8f9ff008477b3d"
-title: "A currency input with currency selector"
----
-A simple custom input that allows users to select a currency and enter a value. Made using <code>createInput()</code>.
-::
-
 ::ExampleCard
 ---
 href: "https://formkit.link/de8e6530b80717f5229813258e739e7b"

From 73263d238285167cbfaf5766d9150c8664e53c1e Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Tue, 7 May 2024 12:50:38 -0400
Subject: [PATCH 20/34] docs: adds changelog for FormKit Pro v.0.124.1

---
 changelog-pro/76.v.0.124.1.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/76.v.0.124.1.md

diff --git a/changelog-pro/76.v.0.124.1.md b/changelog-pro/76.v.0.124.1.md
new file mode 100644
index 00000000..a1d37b0e
--- /dev/null
+++ b/changelog-pro/76.v.0.124.1.md
@@ -0,0 +1,7 @@
+## 0.124.1
+
+### May 7, 2024
+
+### 🐛 Bug fixes
+
+- Fixes max recursion bug in `currency` input in Safari.

From d2b0092dfb6558f24f60d06d9245e6f07fedc4ad Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Tue, 7 May 2024 13:29:34 -0400
Subject: [PATCH 21/34] docs: adds docs for FormKit Pro v0.124.2

---
 changelog-pro/77.v.0.124.2.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/77.v.0.124.2.md

diff --git a/changelog-pro/77.v.0.124.2.md b/changelog-pro/77.v.0.124.2.md
new file mode 100644
index 00000000..2f073a9e
--- /dev/null
+++ b/changelog-pro/77.v.0.124.2.md
@@ -0,0 +1,7 @@
+## 0.124.2
+
+### May 7, 2024
+
+### 🐛 Bug fixes
+
+- Removes type `tel` from `currency` input. Now uses attr `inputmode` instead.

From 5943f97d6417a1b3ec29c1153fce390c5e082520 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Wed, 8 May 2024 07:29:16 -0400
Subject: [PATCH 22/34] docs: adds changelog for FormKit Pro v0.125.0

---
 changelog-pro/78.v.0.125.0.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/78.v.0.125.0.md

diff --git a/changelog-pro/78.v.0.125.0.md b/changelog-pro/78.v.0.125.0.md
new file mode 100644
index 00000000..9df7f2af
--- /dev/null
+++ b/changelog-pro/78.v.0.125.0.md
@@ -0,0 +1,7 @@
+## 0.125.0
+
+### May 8, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue preventing tree shaking of FormKit Pro inputs.

From 055edc0a0e9dae4b7bfe94652506f293c9ae3d78 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Wed, 8 May 2024 10:40:59 -0400
Subject: [PATCH 23/34] docs: removes reverse mask example

---
 inputs/mask.md | 18 ------------------
 1 file changed, 18 deletions(-)

diff --git a/inputs/mask.md b/inputs/mask.md
index 71fbee8b..fa1c433c 100644
--- a/inputs/mask.md
+++ b/inputs/mask.md
@@ -319,24 +319,6 @@ label: "Values can't match the mask"
   Your prefix and suffix content can't match the mask. For instance, if your mask has a digit token <code>#</code>, your prefix/suffix can't contain numbers.
 ::
 
-## Running the mask in reverse
-
-In specific circumstances, you may want to run your mask in reverse. The mask will test if user input fulfills the mask from right to left. This is common in currency-type inputs and can be applied by adding the `reverse` prop:
-
-::Example
----
-name: "Mask input"
-file: "_content/_examples/mask/reverse.vue"
----
-::
-
-::Callout
----
-type: "warning"
-label: "Shift mode requirement"
----
-Running a mask in reverse only works in shift mode.
-::
 
 ## Mask values
 

From acc55328f4f2dccd800cd82db49a48a5c729e8ad Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Thu, 9 May 2024 11:16:49 -0400
Subject: [PATCH 24/34] docs: adds changelog for FormKit Pro v0.125.1

---
 changelog-pro/79.v.0.125.1.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 changelog-pro/79.v.0.125.1.md

diff --git a/changelog-pro/79.v.0.125.1.md b/changelog-pro/79.v.0.125.1.md
new file mode 100644
index 00000000..3bf4f57c
--- /dev/null
+++ b/changelog-pro/79.v.0.125.1.md
@@ -0,0 +1,8 @@
+## 0.125.1
+
+### May 9, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issues with dropdown family inputs introduced by 0.125.0 [#1346](https://github.com/formkit/formkit/issues/1346) and 
+[#1345](https://github.com/formkit/formkit/issues/1345)

From 059279f4a7ef58c8d6fdef1a758b6e61c9e5e744 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Fri, 10 May 2024 09:59:49 -0400
Subject: [PATCH 25/34] docs: adds keyboard interactions table to currency
 input

---
 inputs/currency.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/inputs/currency.md b/inputs/currency.md
index 83a93483..c0dd801e 100644
--- a/inputs/currency.md
+++ b/inputs/currency.md
@@ -140,3 +140,16 @@ help-content: "How much do you want to donate?"
 message-content: "That's a lot of money"
 ---
 ::
+### Keyboard Interactions
+
+::KeyboardEventsTable
+---
+data: [
+  {
+    event: ["up", "down"],
+    separator: '',
+    description: "Increments through input value by current amount.",
+  },
+]
+---
+::
\ No newline at end of file

From aa4eefc208cf95bb724403a48ad1f284f401f2e9 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Fri, 10 May 2024 10:00:21 -0400
Subject: [PATCH 26/34] docs: makes slight edit to keyboard interactions for
 currency input

---
 inputs/currency.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/inputs/currency.md b/inputs/currency.md
index c0dd801e..c9011c33 100644
--- a/inputs/currency.md
+++ b/inputs/currency.md
@@ -148,7 +148,7 @@ data: [
   {
     event: ["up", "down"],
     separator: '',
-    description: "Increments through input value by current amount.",
+    description: "Increments through input value by current step amount.",
   },
 ]
 ---

From c658cbff26c750dbe30edc35e10c57c0341d32c2 Mon Sep 17 00:00:00 2001
From: Andrew Boyd <andrew@formkit.com>
Date: Fri, 10 May 2024 10:19:05 -0400
Subject: [PATCH 27/34] docs: adds more pro changelogs

---
 changelog-pro/80.v.0.125.2.md | 7 +++++++
 changelog-pro/81.v.0.125.3.md | 7 +++++++
 2 files changed, 14 insertions(+)
 create mode 100644 changelog-pro/80.v.0.125.2.md
 create mode 100644 changelog-pro/81.v.0.125.3.md

diff --git a/changelog-pro/80.v.0.125.2.md b/changelog-pro/80.v.0.125.2.md
new file mode 100644
index 00000000..a8a9bee1
--- /dev/null
+++ b/changelog-pro/80.v.0.125.2.md
@@ -0,0 +1,7 @@
+## 0.125.2
+
+### May 9, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue where Slider input `min` and `max` values were not being applied reactively to associated inputs when `show-inputs` prop was enabled. [#1341](https://github.com/formkit/formkit/issues/1341)
diff --git a/changelog-pro/81.v.0.125.3.md b/changelog-pro/81.v.0.125.3.md
new file mode 100644
index 00000000..05c80485
--- /dev/null
+++ b/changelog-pro/81.v.0.125.3.md
@@ -0,0 +1,7 @@
+## 0.125.3
+
+### May 10, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue where Slider number inputs were unable to accept decimal input. [#1341](https://github.com/formkit/formkit/issues/1341)

From 33b2cb0f730c36f7fb34b584f5024fe7f459630e Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Fri, 10 May 2024 11:20:09 -0400
Subject: [PATCH 28/34] docs: adds changelog for FormKit Pro v0.125.4

---
 changelog-pro/82.v.0.125.4.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/82.v.0.125.4.md

diff --git a/changelog-pro/82.v.0.125.4.md b/changelog-pro/82.v.0.125.4.md
new file mode 100644
index 00000000..e7f920d8
--- /dev/null
+++ b/changelog-pro/82.v.0.125.4.md
@@ -0,0 +1,7 @@
+## 0.125.4
+
+### May 10, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue where `currency` input when using either the `max` or `min` prop did not allow the use of decimal points [#1344](https://github.com/formkit/formkit/issues/1344).

From 216a6c51f0cee3838b054b9d82779ddb9cb2eee5 Mon Sep 17 00:00:00 2001
From: Justin Schroeder <justin@formkit.com>
Date: Tue, 14 May 2024 13:42:42 -0400
Subject: [PATCH 29/34] feat: 1.6.3 changelog

---
 api-reference/context.md | 15 +++++++++++++++
 changelog/32.v1.6.2.md   | 15 +++++++++------
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/api-reference/context.md b/api-reference/context.md
index 255ab776..2fb1ea38 100644
--- a/api-reference/context.md
+++ b/api-reference/context.md
@@ -175,11 +175,26 @@ Current state of the input:
    * list, or form, this is true if any children have errors on them.
    */
   errors: boolean
+  /**
+   * Determines if the input should be considered "invalid" — note that this
+   * is not the opposite of the valid state. A valid input is one where the
+   * input is not loading, not pending validation, not unsettled, and
+   * passes all validation rules. An invalid input is one whose validation
+   * rules are not explicitly not passing, and those rules are visible to the user.
+   */
+  invalid: boolean | undefined
   /**
    * The loading state of the input or form. This property is only added while
    * the input is loading and is removed when loading is complete.
    */
   loading: true | undefined
+  /**
+   * If the input is passing all validation rules. This state will remain
+   * in its current state until validation has completed, so if the input
+   * is not passing, and you have a long running validation rule this will
+   * remaining not passing until that rule has resolved.
+   */
+  passing?: boolean
   /**
    * Indicates if the input is has the "required" validation rule.
    */
diff --git a/changelog/32.v1.6.2.md b/changelog/32.v1.6.2.md
index 198eb653..92930941 100644
--- a/changelog/32.v1.6.2.md
+++ b/changelog/32.v1.6.2.md
@@ -1,9 +1,12 @@
-## 1.6.2
+## 1.6.3
 
-### April 8, 2024
+### May 14, 2024
 
-### 🐛 Bug fixes
+## 💪 New Features
+- New clear on submit option for local storage
+- New `context.state.passing` property indicates whether or not a given input is passing all its validation rules.
 
-- Widens unocss compatibility for the `@formkit/themes` package ([#1281](https://github.com/formkit/formkit/issues/1281)).
-- Small German translation fix ([#1293](https://github.com/formkit/formkit/issues/1293)).
-- Adds additional dependencies to the `create-app` cli command ([#1233](https://github.com/formkit/formkit/issues/1233)).
\ No newline at end of file
+## 🐛 Bug fixes
+- Fixes auto animate plugin for FormKit components ([#1354](https://github.com/formkit/formkit/issues/1354)).
+- On multi-step inputs `beforeStepChange` is no longer called when the step cannot be advanced ([#1191](https://github.com/formkit/formkit/issues/1191)).
+- Quickly typing into an input no longer causes an invalid state flicker ([#1324](https://github.com/formkit/formkit/issues/1324)).
\ No newline at end of file

From dc0ab8a11eb8dc2ad9a5324c8e388348a3e62d70 Mon Sep 17 00:00:00 2001
From: Andrew Boyd <andrew@formkit.com>
Date: Tue, 14 May 2024 14:21:33 -0400
Subject: [PATCH 30/34] docs: updates pro changelog and adds colorpicker alpha
 example

---
 .examples/colorpicker/alpha.vue | 16 ++++++++++++++++
 changelog-pro/63.v.0.122.17.md  |  2 +-
 changelog-pro/83.v.0.125.5.md   | 13 +++++++++++++
 inputs/colorpicker.md           | 18 ++++++++++++++++++
 4 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 .examples/colorpicker/alpha.vue
 create mode 100644 changelog-pro/83.v.0.125.5.md

diff --git a/.examples/colorpicker/alpha.vue b/.examples/colorpicker/alpha.vue
new file mode 100644
index 00000000..059777cb
--- /dev/null
+++ b/.examples/colorpicker/alpha.vue
@@ -0,0 +1,16 @@
+<template>
+  <FormKit type="form" #default="{ value }" :actions="false">
+    <!-- %partial% -->
+    <FormKit
+      type="colorpicker"
+      name="color"
+      value="rgba(255, 0, 0, 0.5)"
+      alpha="false"
+      popover
+      value-format="rgba"
+    />
+    <!-- %partial% -->
+
+    <pre wrap>{{ value }}</pre>
+  </FormKit>
+</template>
diff --git a/changelog-pro/63.v.0.122.17.md b/changelog-pro/63.v.0.122.17.md
index 802dfd94..b779c62c 100644
--- a/changelog-pro/63.v.0.122.17.md
+++ b/changelog-pro/63.v.0.122.17.md
@@ -2,6 +2,6 @@
 
 ### April 22, 2024
 
-### 🐛 Features
+### 💪 New Features
 
 - Makes `optionsLoader` function available as a prop for dropdown family inputs.
\ No newline at end of file
diff --git a/changelog-pro/83.v.0.125.5.md b/changelog-pro/83.v.0.125.5.md
new file mode 100644
index 00000000..1c9a28ff
--- /dev/null
+++ b/changelog-pro/83.v.0.125.5.md
@@ -0,0 +1,13 @@
+## 0.125.5
+
+### May 14, 2024
+
+### 💪 New Features
+
+- The `colorpicker` input now has an `alpha` prop which allows users to disable the alpha channel in the color picker [#1302](https://github.com/formkit/formkit/issues/1302)
+
+### 🐛 Bug fixes
+
+- Fixes issue where `dropdown` family inputs' listbox position would be incorrect when opened, inverted, and filtered while in `popover` mode. [#1310](https://github.com/formkit/formkit/issues/1310)
+- Fixes issue where `dropdown` family inputs could trigger a javascript error due to having `id` attributes that were valid yet incompatible with `querySelector` syntax. [#1313](https://github.com/formkit/formkit/issues/1313)
+- Fixes issue where linked inputs for the `slider` would not have reactive `min` and `max` properties. [#1341](https://github.com/formkit/formkit/issues/1341)
diff --git a/inputs/colorpicker.md b/inputs/colorpicker.md
index 92e06939..4805ef12 100644
--- a/inputs/colorpicker.md
+++ b/inputs/colorpicker.md
@@ -51,6 +51,18 @@ There may be times where you wish to show one format to users as a default but r
 ---
 ::
 
+### Disabling the alpha channel
+
+You can disable the alpha channel in the `colorpicker` by setting the `alpha` prop to `false`. This will enforce full opacity on values. Any values with an alpha channel will be converted to full opacity.
+
+::Example
+---
+  name: "Color input"
+  file: "_content/_examples/colorpicker/alpha.vue"
+  minHeight: 400
+---
+::
+
 ## Swatches
 
 Swatches are provided using the `options` prop and use the same `options` API as the `select`, `dropdown`, `autocomplete` and `taglist` inputs from FormKit.
@@ -138,6 +150,12 @@ data: [
     default: "hex",
     description: "The format that the <code>colorpicker</code> input should show in the input preview and be the default setting for the picker panel input. Can be set to <code>hex</code>, <code>hsla</code> or <code>rgba</code>.",
   },
+  {
+    prop: "alpha",
+    type: "boolean",
+    default: "true",
+    description: "When set to <code>false</code> the alpha channel will be disabled in the color picker.",
+  },
   {
     prop: "value-format",
     type: "string",

From f11bfc73ab5dceda73d623d89c94b1ca63e9a266 Mon Sep 17 00:00:00 2001
From: Andrew Boyd <andrew@formkit.com>
Date: Tue, 14 May 2024 14:29:52 -0400
Subject: [PATCH 31/34] chore: fix heading level in changelog

---
 changelog/{32.v1.6.2.md => 33.v1.6.2.md} | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
 rename changelog/{32.v1.6.2.md => 33.v1.6.2.md} (93%)

diff --git a/changelog/32.v1.6.2.md b/changelog/33.v1.6.2.md
similarity index 93%
rename from changelog/32.v1.6.2.md
rename to changelog/33.v1.6.2.md
index 92930941..479e1ca2 100644
--- a/changelog/32.v1.6.2.md
+++ b/changelog/33.v1.6.2.md
@@ -2,11 +2,11 @@
 
 ### May 14, 2024
 
-## 💪 New Features
+### 💪 New Features
 - New clear on submit option for local storage
 - New `context.state.passing` property indicates whether or not a given input is passing all its validation rules.
 
-## 🐛 Bug fixes
+### 🐛 Bug fixes
 - Fixes auto animate plugin for FormKit components ([#1354](https://github.com/formkit/formkit/issues/1354)).
 - On multi-step inputs `beforeStepChange` is no longer called when the step cannot be advanced ([#1191](https://github.com/formkit/formkit/issues/1191)).
 - Quickly typing into an input no longer causes an invalid state flicker ([#1324](https://github.com/formkit/formkit/issues/1324)).
\ No newline at end of file

From c3f4a1bdbc973f01670dc2b9f544634d388f6bd1 Mon Sep 17 00:00:00 2001
From: Andrew Boyd <andrew@formkit.com>
Date: Tue, 14 May 2024 15:24:51 -0400
Subject: [PATCH 32/34] docs: adds changelog for pro

---
 changelog-pro/84.v.0.125.6.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/84.v.0.125.6.md

diff --git a/changelog-pro/84.v.0.125.6.md b/changelog-pro/84.v.0.125.6.md
new file mode 100644
index 00000000..6ad2dbff
--- /dev/null
+++ b/changelog-pro/84.v.0.125.6.md
@@ -0,0 +1,7 @@
+## 0.125.5
+
+### May 14, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue where schema sections in Pro inputs with existing `meta` keys were not being assigned programmatic `meta` values. This was preventing the `eachSection` helper function from being able access some sections — which in turn was preventing the AutoAnimate plugin from being able to be applied to repeater items. Whew... this one was a doozy. 😅
\ No newline at end of file

From 60e92e4a45f34d594aedb09ff822957612767584 Mon Sep 17 00:00:00 2001
From: Sasha Milenkovic <sasha@formkit.com>
Date: Tue, 14 May 2024 16:01:54 -0400
Subject: [PATCH 33/34] docs: adds changelog for formkit pro v0.125.7

---
 changelog-pro/85.v.0.125.7.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 changelog-pro/85.v.0.125.7.md

diff --git a/changelog-pro/85.v.0.125.7.md b/changelog-pro/85.v.0.125.7.md
new file mode 100644
index 00000000..518f85cc
--- /dev/null
+++ b/changelog-pro/85.v.0.125.7.md
@@ -0,0 +1,7 @@
+## 0.125.7
+
+### May 14, 2024
+
+### 🐛 Bug fixes
+
+- Fixes issue where auto-animate plugin would conflict with drag and drop animations on repeater input.
\ No newline at end of file

From 71f9f7b673f2ddbcbb5c573e8102acbf4d517ba5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20Rish=C3=B8j?= <christian@rishoj.net>
Date: Sat, 18 May 2024 15:53:19 +0200
Subject: [PATCH 34/34] added typebox plugin docs

---
 .examples/typebox/errors.vue                  | 50 +++++++++++
 .examples/typebox/importMap.json              |  3 +
 .examples/typebox/validation.vue              | 51 +++++++++++
 .examples/typebox/with-formkit-validation.vue | 63 +++++++++++++
 api-reference/formkit-typebox.md              | 36 ++++++++
 plugins/typebox.md                            | 88 +++++++++++++++++++
 6 files changed, 291 insertions(+)
 create mode 100644 .examples/typebox/errors.vue
 create mode 100644 .examples/typebox/importMap.json
 create mode 100644 .examples/typebox/validation.vue
 create mode 100644 .examples/typebox/with-formkit-validation.vue
 create mode 100644 api-reference/formkit-typebox.md
 create mode 100644 plugins/typebox.md

diff --git a/.examples/typebox/errors.vue b/.examples/typebox/errors.vue
new file mode 100644
index 00000000..60dedcab
--- /dev/null
+++ b/.examples/typebox/errors.vue
@@ -0,0 +1,50 @@
+<script setup>
+import { createTypeboxPlugin } from '@formkit/typebox'
+import { Type } from '@sinclair/typebox'
+import { TypeCompiler } from '@sinclair/typebox/compiler'
+
+// some setup code
+const typeboxSchema = Type.Object({
+  personalInfo: Type.Object({
+    firstName: Type.String({ minLength: 3, maxLength: 25 }),
+    lastName: Type.String({ minLength: 3, maxLength: 25 }),
+  }),
+  missingField: Type.Number()
+})
+const [typeboxPlugin, submitHandler] = createTypeboxPlugin(typeboxSchema, async () => { await new Promise((r) => setTimeout(r, 2000))})
+
+// In a real app, you'd likely get the errors from
+// your server, but for this example we'll do the
+// parsing and retrieve the errors here.
+function setupFormNode(node) {
+  const invalidValues = {personalInfo: { firstName: 'A', lastName: 'K' },
+    missingField: 'not a number'
+  }
+  const checker = TypeCompiler.Compile(typeboxSchema)
+  const errors = checker.Errors(invalidValues)
+  // pass the ValueErrorIterator from Typebox to the setTypeboxErrors method
+  // which is added by the Typebox plugin.
+  node.setTypeboxErrors(errors)
+}
+</script>
+
+<template>
+  <h1 class="text-2xl font-bold mb-2">Errors set with node.setTypeboxErrors()</h1>
+  <p class="text-base mb-4">
+    This form cannot be successfully submitted because
+    the form fields do not match the provided schema.<br>
+    This is done to illustrate hydration of form-level errors.<br>
+    Do not actually do this. :)
+  </p>
+  <FormKit
+    type="form"
+    @node="setupFormNode"
+    :plugins="[typeboxPlugin]"
+    @submit="submitHandler"
+  >
+    <FormKit type="group" name="personalInfo">
+      <FormKit type="text" name="firstName" label="First Name" />
+      <FormKit type="text" name="lastName" label="Last Name" />
+    </FormKit>
+  </FormKit>
+</template>
diff --git a/.examples/typebox/importMap.json b/.examples/typebox/importMap.json
new file mode 100644
index 00000000..04cf4d8a
--- /dev/null
+++ b/.examples/typebox/importMap.json
@@ -0,0 +1,3 @@
+{
+  "typebox": "https://cdn.jsdelivr.net/npm/@sinclair/typebox@0.32.30/build/cjs/index.min.js"
+}
diff --git a/.examples/typebox/validation.vue b/.examples/typebox/validation.vue
new file mode 100644
index 00000000..2b8eea33
--- /dev/null
+++ b/.examples/typebox/validation.vue
@@ -0,0 +1,51 @@
+<script setup>
+import { createTypeboxPlugin } from '@formkit/typebox'
+import { Type } from '@sinclair/typebox'
+import { FormatRegistry } from '@sinclair/typebox'
+
+// http://www.w3.org/TR/html5/forms.html#valid-e-mail-address (search for 'wilful violation')
+const emailPattern = /^[a-z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/i
+FormatRegistry.Set('email', (value) => emailPattern.test(value))
+
+const typeboxSchema = Type.Object({
+  personalInfo: Type.Object({
+    firstName: Type.String({minLength: 3, maxLength: 25}),
+    lastName: Type.String({minLength: 3, maxLength: 25}),
+  }),
+  email: Type.String({format: 'email'}),
+  arrayMin: Type.Array(Type.String(), {min: 2}),
+})
+
+const [typeboxPlugin, submitHandler] = createTypeboxPlugin(
+  typeboxSchema,
+  async (formData) => {
+    // fake submit handler, but this is where you
+    // do something with your valid data.
+    await new Promise((r) => setTimeout(r, 2000))
+    alert('Form was submitted!')
+    console.log(formData)
+  }
+)
+</script>
+
+<template>
+  <h1>Validation from Typebox schema</h1>
+  <FormKit type="form" :plugins="[typeboxPlugin]" @submit="submitHandler">
+    <FormKit type="group" name="personalInfo">
+      <FormKit
+        validation-visibility="live"
+        type="text"
+        name="firstName"
+        label="First Name"
+      />
+      <FormKit type="text" name="lastName" label="Last Name" />
+    </FormKit>
+    <FormKit type="text" name="email" label="Your email" />
+    <FormKit
+      type="checkbox"
+      name="arrayMin"
+      label="Typebox features"
+      :options="['Validation', 'Type-Safety', 'Reusability']"
+    />
+  </FormKit>
+</template>
diff --git a/.examples/typebox/with-formkit-validation.vue b/.examples/typebox/with-formkit-validation.vue
new file mode 100644
index 00000000..617817e6
--- /dev/null
+++ b/.examples/typebox/with-formkit-validation.vue
@@ -0,0 +1,63 @@
+<script setup>
+import { createTypeboxPlugin } from '@formkit/typebox'
+import { Type } from '@sinclair/typebox'
+import { FormatRegistry } from '@sinclair/typebox'
+
+// http://www.w3.org/TR/html5/forms.html#valid-e-mail-address (search for 'wilful violation')
+const emailPattern = /^[a-z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/i
+FormatRegistry.Set('email', (value) => emailPattern.test(value))
+
+const typeboxSchema = Type.Object({
+  personalInfo: Type.Object({
+    firstName: Type.String({minLength: 3, maxLength: 25}),
+    lastName: Type.String({minLength: 3, maxLength: 25}),
+  }),
+  email: Type.string({format: 'email'}),
+  arrayMin: Type.Array(Type.String(), {min: 2}),
+})
+
+const [typeboxPlugin, submitHandler] = createTypeboxPlugin(
+  typeboxSchema,
+  async (formData) => {
+    // fake submit handler, but this is where you
+    // do something with your valid data.
+    await new Promise((r) => setTimeout(r, 2000))
+    alert('Form was submitted!')
+    console.log(formData)
+  }
+)
+</script>
+
+<template>
+  <h1 class="text-2xl font-bold mb-4">Typebox with FormKit Validation</h1>
+  <FormKit type="form" :plugins="[typeboxPlugin]" @submit="submitHandler">
+    <FormKit type="group" name="personalInfo">
+      <FormKit
+        validation="required|length:3,25"
+        validation-visibility="live"
+        type="text"
+        name="firstName"
+        label="First name"
+      />
+      <FormKit
+        validation="required|length:3,25"
+        type="text"
+        name="lastName"
+        label="Last name"
+      />
+    </FormKit>
+    <FormKit
+      validation="required|email"
+      type="text"
+      name="email"
+      label="Your email"
+    />
+    <FormKit
+      validation="required|min:2"
+      type="checkbox"
+      name="arrayMin"
+      label="Typebox features"
+      :options="['Validation', 'Type-Safety', 'Reusability']"
+    />
+  </FormKit>
+</template>
diff --git a/api-reference/formkit-typebox.md b/api-reference/formkit-typebox.md
new file mode 100644
index 00000000..37d10ab9
--- /dev/null
+++ b/api-reference/formkit-typebox.md
@@ -0,0 +1,36 @@
+---
+title: formkit/typebox
+---
+
+# @formkit/typebox
+
+<page-toc></page-toc>
+
+## Introduction
+
+The first-party typebox package/plugin for FormKit. Read the [documentation](https://formkit.com/essentials/typebox) for usage instructions.
+
+## Functions
+
+### createTypeboxPlugin()
+
+Creates a new Typebox schema plugin for form validation.
+
+#### Signature
+
+<client-only>
+
+```typescript
+createTypeboxPlugin<T extends TSchema>(typeboxSchema: T, submitCallback: (payload: Static<typeof typeboxSchema>, node: FormKitNode | undefined) => void | Promise<void>): [FormKitPlugin, (payload: any, node: FormKitNode | undefined) => void];
+```
+
+</client-only>
+
+#### Parameters
+
+- `typeboxSchema` — A Typebox schema to validate the form against.
+- `submitCallback` — A callback to run when the form is submitted and it passes validation.
+
+#### Returns
+
+ A tuple of a [FormKitPlugin](/api-reference/formkit-core#formkitplugin) and a submit handler.
diff --git a/plugins/typebox.md b/plugins/typebox.md
new file mode 100644
index 00000000..5f159236
--- /dev/null
+++ b/plugins/typebox.md
@@ -0,0 +1,88 @@
+---
+title: Typebox Plugin
+description: Use your Typebox schema to validate your FormKit forms.
+---
+
+# Typebox Plugin
+
+:PageToc
+
+With the `@formkit/typebox` package you can easily enable validation of your FormKit forms with your Typebox schema. This provides a convenient way to have isomorphic types and ensure that your front-end and back-end are using the same validation rules.
+
+When validating against a Typebox schema all validation errors will be mapped to their corresponding inputs, show or hide based on your form / input's `validation-visibility` prop, and prevent submission when form data does not pass validation with Typebox.
+
+## Installation
+
+To use this plugin with FormKit, install `@formkit/typebox`:
+
+```bash
+yarn add @formkit/typebox
+```
+
+Once you've installed the `@formkit/typebox` package, you'll need to register the plugin on a per-form basis and each form that requires validation with a Typebox schema will create a new instance of the plugin using the `createTypeboxPlugin` function.
+
+## Usage
+
+To use the Typebox plugin we need to import the `createTypeboxPlugin` function from `@formkit/typebox`, call the `createTypeboxPlugin` function to create receive our `typeboxPlugin` and `submitHandler`, and then add them both to our FormKit form.
+
+The `createTypeboxPlugin` function takes two arguments:
+
+- `typeboxSchema`: The Typebox schema that you would like to use to validate against the form.
+- `submitCallback`: a function you would like to run once validation has succeeded on your form — this is where you would handle posting your data to your backend or other submit-related tasks. You form data will be provided with full TypeScript support based on your Typebox schema.
+
+The `createTypeboxPlugin` will return a tuple of:
+
+- `typeboxPlugin`: The plugin that should be applied to your target form's `plugins` prop.
+- `submitHandler`: The submit handler that should be attached to your form's `@submit` action. When the form data passes validation of your provided Typebox schema your `submitCallback` will fire.
+
+### For form validation
+
+Here is an example of using a Typebox schema to validate a FormKit form. It's important that your FormKit input `name`s match the expected values for your Typebox schema.
+
+::Example
+---
+name: 'Typebox Validation'
+file: [
+'/\_content/_examples/typebox/validation.vue',
+]
+import-map: '/\_content/_examples/typebox/importMap.json'
+---
+::
+
+Now your FormKit form will use your Typebox Schema for validation — and all messages will adjacent to each matching FormKit just live native FormKit validation!
+
+### In addition to FormKit validation
+
+Using Typebox to validate your form doesn't mean you have to forgo using FormKit's built-in validation messages. If you add FormKit validation to your FormKit inputs then Typebox validation errors will only show if all FormKit validations have been satisfied and there are remaining unsatisfied Typebox validations.
+
+This has a few benefits:
+
+- You can use FormKit's built-in rules such as `confirm` which don't have easy-to-use equivalents within Typebox.
+- Your messages can be translated to one of the many existing languges in `@formkit/i18n` without any additional effort on your part.
+- The built-in FormKit validation messages are written to be contextually aware of your input names and knowing that they will be attached directly to their corresponding inputs — so they are more precise and easier to understand than their generic Typebox counterparts.
+
+Here's the same form as before, but now using FormKit validation messages in addition to Typebox schema validation.
+
+::Example
+---
+name: 'Typebox Validation with FormKit Validation'
+file: [
+'/\_content/_examples/typebox/with-formkit-validation.vue',
+]
+import-map: '/\_content/_examples/typebox/importMap.json'
+---
+::
+
+### For setting form errors
+
+If you need to set errors on your form you can do so with the `node.setTypeboxErrors` function that is made available by the `typeboxPlugin`. The `node.setTypeboxErrors` function accepts a Typebox `ValueErrorIterator` and will map the errors to each input. Any non-matching errors will be shown as form-level errors.
+
+::Example
+---
+name: 'Typebox Errors'
+file: [
+'/\_content/_examples/typebox/errors.vue',
+]
+import-map: '/\_content/_examples/typebox/importMap.json'
+---
+::