The simplest way to get a new project started with FormKit is by using FormKit CLI's create-app
. Alternatively, if you already have a project, you can manually install with Vue, with Nuxt or with Astro.
You can also try out all FormKit features using our playground.
create-app
is the fastest way to start a new project with FormKit pre-configured for you. It walks you through all the necessary steps, and allows you to optionally add TypeScript support, use Nuxt or Vite as your starting template, or set up Pro Inputs.
At your terminal, run npx formkit create-app
to start your new project:
npx formkit create-app
create-app
will ask you some questions about your project so it can determine what it needs to install and setup for you:
✔ Please enter a name for the project › <your-project-name>
✔ What framework would you like to use? › Vite / Nuxt
✔ What language should be used? › TypeScript / Javascript
✔ Would you like to install FormKit Pro? › no / yes
✔ Enter a project key from https://pro.formkit.com: › <fk-00000000000>
Once this is completed, you can follow the instructions to install all dependencies and start a development server:
Created formkit-app!
To run your new app:
📁 cd <your-project-name>
✅ npm install
🚀 npm run dev
Most new projects use a build tool like Vite, Snowpack, or webpack. This makes installing npm dependencies a piece of cake 🍰:
npm install @formkit/vue
You can install the upcoming version of FormKit (unstable) anytime by opting to installing the "next" version tag: npm install @formkit/vue@next
FormKit only supports Vue 3. If you're required to use Vue 2 on a project, consider using the spiritual ancestor of FormKit — Vue Formulate.
The @formkit/vue
package ships with a Vue plugin and a default configuration for easy setup:
import { createApp } from 'vue'
import { plugin, defaultConfig } from '@formkit/vue'
import App from 'App.vue'
createApp(App).use(plugin, defaultConfig).mount('#app')
// remember, each Vue plugin needs its own .use()
// .use(router).use(plugin2)
That's it! You're now ready to use the <FormKit>
component in your Vue 3 application.
Using FormKit with Nuxt requires minimal setup. First include the Nuxt module as a dependency within your project:
npm install @formkit/nuxt
FormKit only supports Nuxt 3. If you're required to use Nuxt 2 on a project, consider using the spiritual ancestor of FormKit — Vue Formulate — which also ships with its own Nuxt module.
Then in your nuxt.config
file add the module to your modules list:
// nuxt.config
export default defineNuxtConfig({
modules: ['@formkit/nuxt'],
})
That's it! FormKit is now registered in your project using the default config and you can start using the <FormKit>
component.
First, we need to install Astro's Vue integration. You can refer to Astro's Vue integration docs for more detail.
Inside of Astro's config file (astro.config.*
), let's add an entrypoint _app
. The _app
entrypoint file is just a configuration file for Vue:
// astro.config.mjs
import { defineConfig } from 'astro/config'
import vue from '@astrojs/vue'
export default defineConfig({
integrations: [vue({ appEntrypoint: '/src/pages/_app' })],
})
Next, install the @formKit/vue
package:
npm install @formkit/vue
The @formkit/vue
package ships with a Vue plugin and a default configuration for easy setup:
// src/pages/_app.ts
import type { App } from 'vue'
import { plugin, defaultConfig } from '@formkit/vue'
export default (app: App) => {
app.use(plugin, defaultConfig)
}
Astro does not let you use FormKit
directly inside Astro files, so you should create a wrapper around your forms.
Now you can add FormKit to your Astro Vue components, so that you can create a component inside the components folder:
<script setup>
// src/components/Form.vue
const submitHandler = async (fields) => {
// Let's pretend this is an ajax request:
await new Promise((r) => setTimeout(r, 1000))
console.log(fields)
}
</script>
<template>
<FormKit type="form" @submit="submitHandler">
<FormKit type="text" label="Name" name: "name" />
<FormKit type="email" label="Email" name: "email" />
</FormKit>
</template>
After that, you just need to import and use it inside your Astro files:
FormKit works best with client hydration enabled, so make sure to use client:visible
or client:load
.
// src/pages/index.astro
---
import Form from '../components/Form.vue';
---
<Form client:visible />
That's it! You're now ready to use the <FormKit>
component in your Astro application.
If you would like to supply your own configuration, you can either extend defaultConfig
by passing a configuration object to it, or replace with your own configuration object, which allows for improved tree-shaking (only include the rules and languages you want to actually use) and more fine-grained control:
FormKit uses a unique hierarchical configuration system that is well suited for forms, meaning that all configurations defined globally are available to all inputs.
// formkit.config.js
import { fr } from '@formkit/i18n'
const config = {
locales: { fr },
locale: 'fr',
}
export default config
// app.js or _app.ts for Astro
import config from 'formkit.config.js'
app.use(plugin, defaultConfig(config))
Nuxt already automatically uses formkit.config.js
that is at the root of your project to extend FormKit's functionality.
This configuration file will be automatically included if detected in your project directory. If you would like to supply a custom
path to your formkit.config
, you can override the default location using the configFile
option under the formkit
key.
Any path you supply should be relative to the root of your Nuxt project:
// nuxt.config
export default defineNuxtConfig({
modules: ['@formkit/nuxt'],
formkit: {
configFile: './my-configs/formkit.config.mjs',
},
})
By default, your configuration will extend the defaultConfig
that ships with FormKit. This is the desired behavior
for the majority of projects. However, if you need to define the entire FormKit config yourself — from scratch — you may do so
by setting the defaultConfig
option for the module to false
:
// nuxt.config
export default defineNuxtConfig({
modules: ['@formkit/nuxt'],
formkit: {
defaultConfig: false,
configFile: './my/custom/location/formkit.config.ts',
// ^ this is now a full config replacement, not override.
},
})
For TypeScript users, it can be helpful to type your formkit.config.ts
export as DefaultConfigOptions
explicitly:
// formkit.config.ts
import { fr } from '@formkit/i18n'
import { DefaultConfigOptions } from '@formkit/vue'
const config: DefaultConfigOptions = {
locales: { fr },
locale: 'fr',
}
export default config
The default FormKit theme (called "genesis") can be added via CDN or by installing the @formkit/themes
package.
To load genesis
via CDN, supply it to the theme
property of your defaultConfig
:
If you're using nuxt your configuration would be inside of formkit.config.ts
...
defaultConfig({
theme: 'genesis' // will load from CDN and inject into document head
})
...
npm install @formkit/themes
Assuming you are using a bundler like Vite, Webpack or Nuxt — you can then directly import the theme:
// main.js or formkit.config.ts
import '@formkit/themes/genesis'
FormKit ships with a Tailwind version of the Genesis theme. To use this pre-made Tailwind theme in your project import it from @formkit/themes/dist/tailwindcss/genesis
and add it to your formkit.config.js
. You'll also want to include the neccessary genesisIcons
import from @formkit/icons
.
// formkit.config.js
import { generateClasses } from '@formkit/themes'
import { genesisIcons } from '@formkit/icons'
import genesis from '@formkit/themes/tailwindcss/genesis'
export default {
icons: {
...genesisIcons,
},
config: {
classes: generateClasses(genesis),
},
}
The genesis
theme import is nice for brevity, but the Tailwind parser will need to be provided the path to the full theme file in your node_modules
in order to know which classes are being used. Additionally you should add the FormKitVariants
plugin to your tailwind.config.js
in order to make use of helpful FormKit variants such as formkit-invalid:
in your project.
// tailwind.config.js
const FormKitVariants = require('@formkit/themes/tailwindcss')
module.exports = {
content: [
'./src/**/*.{html,js,vue}',
'./node_modules/@formkit/themes/dist/tailwindcss/genesis/index.cjs',
],
plugins: [FormKitVariants],
}
Installing FormKit Pro is easy! Here are the steps:
Login to your FormKit Pro account at pro.formkit.com and create a project. A Project Key
will be provided to you.
Next, install the @formkit/pro
:
npm install @formkit/pro
Import the createProPlugin
helper and any desired Pro Inputs from @formkit/pro
:
// main.js or formkit.config.ts
import { createProPlugin, rating, toggle } from '@formkit/pro'
Create the Pro plugin with your Project Key
and desired Pro Inputs:
// main.js or formkit.config.ts
const proPlugin = createProPlugin('fk-00000000000', {
rating,
toggle,
// ... and any other Pro Inputs
})
Lastly, add the plugin to your FormKit config:
If you're using nuxt your configuration would be inside of formkit.config.ts
// main.js or formkit.config.ts
const config = defaultConfig({
plugins: [proPlugin],
})
Formkit extends the default Genesis theme for Pro Inputs. You can directly import it:
// main.js or formkit.config.ts
// Genesis for Pro is dependent on Genesis
import '@formkit/themes/genesis'
import '@formkit/pro/genesis'
That's it! now your pro inputs should be beautifully styled.