Installation

    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.

    With create-app

    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.

    Run the FormKit CLI

    At your terminal, run npx formkit create-app to start your new project:

    create-app will ask you some questions about your project so it can determine what it needs to install and setup for you:

    Once this is completed, you can follow the instructions to install all dependencies and start a development server:

    With Vue

    Most new projects use a build tool like Vite, Snowpack, or webpack. This makes installing npm dependencies a piece of cake 🍰:

    The @formkit/vue package ships with a Vue plugin and a default configuration for easy setup:

    That's it! You're now ready to use the <FormKit> component in your Vue 3 application. The defaultConfig includes all of FormKit's inputs, validation rules, and the English language. You can replace the defaultConfig with your own configuration, which allows for improved tree-shaking (only include the rules and languages you want to actually use) and more fine-grained control.

    next
    You can install the upcoming version of FormKit (unstable) anytime by opting to installing the "next" version tag: npm install @formkit/vue@next
    Vue 2
    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.

    Default theme

    The default FormKit theme (called "genesis") can be added via CDN or by installing the @formkit/themes package.

    CDN Usage

    To load genesis via CDN, supply it to the theme property of your defaultConfig:

    Direct import

    Assuming you are using a bundler like Vite, Webpack or Nuxt — you can then directly import the theme:

    Pro Inputs

    Installing FormKit Pro is easy! Here are the steps:

    1. Get a Project Key

    Login to your FormKit Pro account at pro.formkit.com and create a project. A Project Key will be provided to you.

    2. Install the package

    Next, install the @formkit/pro package using npm, yarn, or other package manager:

    3. Configure your project

    Import the createProPlugin helper and any desired Pro Inputs from @formkit/pro:

    Create the Pro plugin with your Project Key and desired Pro Inputs:

    Lastly, add the plugin to your FormKit config:

    Optional Pro theme

    Formkit extends the default Genesis theme for Pro Inputs. You can directly import it:

    Full example with Pro Inputs

    Here's a full example of FormKit and FormKit Pro installed:

    That's it! You will be able to use any registered Pro Inputs in your project now, like <FormKit type="rating" />.

    With Nuxt

    Using FormKit with Nuxt requires minimal setup. First include the Nuxt module as a dependency within your project:

    Then in your nuxt.config file add the module to your modules list:

    That's it! FormKit is now registered in your project using the default config and you can start using the <FormKit> component.

    Configuring with Nuxt

    If you would like to supply your own configuration, create a formkit.config file adjacent to your nuxt.config file. Like the nuxt.config file itself, .ts, .mjs, and .js are all valid file extensions depending on your project's needs:

    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:

    For TypeScript users, it can be helpful to type your formkit.config.ts export as DefaultConfigOptions explicitly:

    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:

    Pro inputs

    Installing FormKit Pro into your Nuxt project is just as easy as it is for Vue.

    1. Get a Project Key

    Login to your FormKit Pro account at pro.formkit.com and create a project. A Project Key will be provided to you.

    2. Install the package

    Next, install the @formkit/pro package using npm, yarn, or another package manager:

    3. Configure your project

    Import the createProPlugin helper and your desired Pro Inputs from @formkit/pro:

    Create the Pro plugin with your Project Key and desired Pro Inputs:

    That's it! FormKit is ready to use and — if you read this far — specifically tailored to your Nuxt project's needs.

    Nuxt 2
    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.

    With Astro

    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:

    Next, install the @formKit/vue package:

    The @formkit/vue package ships with a Vue plugin and a default configuration for easy setup:

    Vue Components
    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:

    After that, you just need to import and use it inside your Astro files:

    Client Hydration
    FormKit works best with client hydration enabled, so make sure to use `client:visible` or `client:load`.

    That's it! You're now ready to use the <FormKit> component in your Astro application. The defaultConfig includes all of FormKit's inputs, validation rules, and the English language. You can replace the defaultConfig with your own configuration, which allows for improved tree-shaking (only include the rules and languages you want to actually use) and more fine-grained control.

    Using Tailwind or another utility framework? Styling docs