Architecture

• Introduction
• Architecture
• Node
  • Input
  • List
  • Group
  • Options
  • Config & Props
  • Props
  • Setting values
  • Value settlement
  • Getting a component’s node
• Traversal
  • Deep traversal
  • Traversal tokens
• Events
  • Add listener
  • Remove listener
  • Core events
  • Emitting events
• Hooks
  • Hook middleware
• Plugins
• Library
• Message store
  • Read and write messages
• Ledger
  • Creating a counter

Introduction

At the heart of the FormKit framework is @formkit/core. This zero-dependency package is responsible for nearly all of FormKit's low-level critical functions, such as:

• Configuration
• Value input/output
• Event bubbling
• Plugin management
• Tree state tracking
• Message management
• Lifecycle hooks

Architecture

The functionality of FormKit core is not exposed to your application via a centralized instance but rather a distributed set of "nodes" (FormKitNode) where each node represents a single input.

This mirrors HTML — in fact DOM structure is actually a general tree and FormKit core nodes reflect this structure. For example, a simple login form could be drawn as the following tree graph:

In this diagram, a form node is a parent to three child nodes — email, password and submit. Each input component in the graph "owns" a FormKit core node, and each node contains its own options, configuration, props, events, plugins, lifecycle hooks, etc. This architecture ensures that FormKit’s primary features are decoupled from the rendering framework (Vue) — a key to reducing side effects and maintaining blazing fast performance.

Additionally, this decentralized architecture allows for tremendous flexibility. For example — one form could use different plugins than other forms in the same app, a group input could modify the configuration of its sub-inputs, and validation rules can even be written to use props from another input.

Node

Every <FormKit> component owns a single core node, and each node must be one of three types:

• Input
• List
• Group

Input

Most of FormKit’s native inputs have a node type of input — they operate on a single value. The value itself can be of any type, such as objects, arrays, strings, and numbers — any value is acceptable. However, nodes of type input are always leafs — meaning they cannot have children.

import { createNode } from '@formkit/core'

const input = createNode({
  type: 'input', // defaults to 'input' if not specified
  value: 'hello node world',
})

console.log(input.value)
// 'hello node world'

List

A list is a node that produces an array value. Children of a list node produce a value in the list’s array value. The names of immediate children are ignored — instead each is assigned an index in the list’s array.

import { createNode } from '@formkit/core'

const list = createNode({
  type: 'list',
  children: [
    createNode({ value: 'paprika@example.com' }),
    createNode({ value: 'bill@example.com' }),
    createNode({ value: 'jenny@example.com' }),
  ],
})

console.log(list.value)
// ['paprika@example.com', 'bill@example.com', 'jenny@example.com']

Group

A group is a node that produces an object value. Children of a group node use their name to produce a property of the same name in the group’s value object — <FormKit type="form"> is an instance of a group.

import { createNode } from '@formkit/core'

const group = createNode({
  type: 'group',
  children: [
    createNode({ name: 'meat', value: 'turkey' }),
    createNode({ name: 'greens', value: 'salad' }),
    createNode({ name: 'sweets', value: 'pie' }),
  ],
})

console.log(group.value)
// { meat: 'turkey', greens: 'salad', sweets: 'pie' }

Options

In addition to specifying the type of node when calling createNode(), you can pass any of the following options:

Config & Props

FormKit uses an inheritance-based configuration system. Any values declared in the config option are automatically passed to children (and all descendants) of that node, but not passed to siblings or parents. Each node can override its inherited values by providing its own config, and these values will in turn be inherited by any deeper children and descendants. For example:

const parent = createNode({
  type: 'group',
  config: {
    color: 'yellow',
  },
  children: [
    createNode({
      type: 'list',
      config: { color: 'pink' },
      children: [createNode(), createNode()],
    }),
    createNode(),
  ],
})

The above code will result in each node having the following configuration:

Props

The node.props and node.config objects are closely related. node.config is best thought of as the initial values for node.props. props is an arbitrarily shaped object that contains details about the current instance of the node.

The best practice is to always read configuration and prop data from node.props even if the original value is defined using node.config. Explicitly defined props take precedence over configuration options.

const child = createNode({
  props: {
    flavor: 'cherry',
  },
})
const parent = createNode({
  type: 'group',
  config: {
    size: 'large',
    flavor: 'grape',
  },
  children: [child],
})
console.log(child.props.size)
// outputs: 'large'
console.log(child.props.flavor)
// outputs: 'cherry'

Setting values

You can set the initial value of a node by providing the value option on createNode() — but FormKit is all about interactivity, so how do we update the value of an already defined node? By using node.input(value).

import { createNode } from '@formkit/core'

const username = createNode()
username.input('jordan-goat98')
console.log(username.value)
// undefined  👀 wait — what!?

In the above example username.value is still undefined immediately after it’s set because node.input() is asynchronous. If you need to read the resulting value after calling node.input() you can await the returned promise.

import { createNode } from '@formkit/core'

const username = createNode()
username.input('jordan-goat98').then(() => {
  console.log(username.value)
  // 'jordan-goat98'
})

Because node.input() is asynchronous, the rest of our form does not need to recompute its dependencies on every keystroke. It also provides an opportunity to perform modifications to the unsettled value before it is "committed" to the rest of the form. However — for internal node use only — a _value property containing the unsettled value of the input is also available.

Value settlement

Now that we understand node.input() is asynchronous, let's explore how FormKit solves the "settled tree" problem. Imagine a user quickly types in their email address and hits "enter" very quickly — thus submitting the form. Since node.input() is asynchronous, incomplete data would likely be submitted. We need a mechanism to know when the whole form has "settled".

To solve this, FormKit’s nodes automatically track tree, subtree, and node "disturbance". This means the form (usually the root node) always knows the settlement state of all the inputs it contains.

The following graph illustrates this "disturbance counting". Click on any input node (blue) to simulate calling node.input() and notice how the whole form is always aware of how many nodes are "disturbed" at any given time. When the root node has a disturbed count of 0 the form is settled and safe to submit.

import { createNode } from '@formkit/node'

const form = createNode({
  type: 'group',
  children: [
    createNode()
    createNode()
    createNode()
  ],
})
// ...
// user interaction:
async function someEvent () {
  await form.settled
  // we now know the form is fully "settled"
  // and that form.value is accurate.
}

Getting a component’s node

Sometimes it can be helpful to get the underlying instance of a node from the Vue <FormKit> component. There are three primary methods of fetching an input’s node.

• Using getNode() (or the Vue plugin’s $formkit.get() for Options API)
• Using the @node event.
• Using a template ref.

Using getNode()

When using FormKit you can access a node by assigning it an id and then accessing it by that property via the getNode() function.

Using the node event

Another way to get the underlying node is to listen to the @node event which is emitted only once when the component first initializes the node.

Using a template ref

Assigning a <FormKit> component to a ref also allows easy access to the node.

Traversal

To traverse nodes within a group or list use node.at(address) — where address is the name of the node being accessed (or the relative path to the name). For example:

import { createNode } from '@formkit/core'

const group = createNode({
  type: 'group',
  children: [createNode({ name: 'email' }), createNode({ name: 'password' })],
})

// Returns the email node
group.at('email')

If the starting node has siblings, it will attempt to locate a match in the siblings (internally, this is what FormKit uses for validation rules like confirm:address).

import { createNode } from '@formkit/core'

const email = createNode({ name: 'email' })
const password = createNode({ name: 'password' })
const group = createNode({
  type: 'group',
  children: [email, password],
})

// Accesses sibling to return the password node
email.at('password')

Deep traversal

You can go deeper than one level by using a dot-syntax relative path. Here's a more complex example:

import { createNode } from '@formkit/core'

const group = createNode({
  type: 'group',
  children: [
    createNode({ name: 'team' }),
    createNode({
      type: 'list',
      name: 'users',
      children: [
        createNode({
          type: 'group',
          children: [
            createNode({ name: 'email' }),
            createNode({ name: 'password', value: 'foo' }),
          ],
        }),
        createNode({
          type: 'group',
          children: [
            createNode({ name: 'email' }),
            createNode({ name: 'password', value: 'fbar' }),
          ],
        }),
      ],
    }),
  ],
})

// outputs: 'foo'
console.log(group.at('users.0.password').value)

Notice how traversing the list uses numeric keys, this is because the list type uses array indexes automatically.

Traversal tokens

Also available for use in node.at() are a few special "tokens":

These tokens are used in dot-syntax addresses just like you would use a node’s name:

import { createNode } from '@formkit/core'

const secondEmail = createNode({ name: 'email' })

createNode({
  type: 'group',
  children: [
    createNode({ name: 'team', value: 'charlie@factory.com' }),
    createNode({
      type: 'list',
      name: 'users',
      children: [
        createNode({
          type: 'group',
          children: [
            createNode({ name: 'email', value: 'james@peach.com' }),
            createNode({ name: 'password', value: 'foo' }),
          ],
        }),
        createNode({
          type: 'group',
          children: [
            secondEmail, // We're going to start here.
            createNode({ name: 'password', value: 'fbar' }),
          ],
        }),
      ],
    }),
  ],
})

// Navigate from the second email to the first
console.log(secondEmail.at('$parent.$parent.0.email').value)
// outputs: charlie@factory.com

Events

Nodes have their own events which are emitted during the node’s lifecycle (unrelated to Vue’s events).

Add listener

To observe a given event, use node.on().

// Listen for any prop being set or changed.
node.on('prop', ({ payload }) => {
  console.log(`prop ${payload.prop} was set to ${payload.value}`)
})

node.props.foo = 'bar'
// outputs: prop foo was set to bar

Event handler callbacks all receive a single argument of type FormKitEvent, the object shape is:

{
  // The contents of the event — a string, an object, etc.
  payload: { cause: 'ice cream', duration: 200 },
  // The name of the event, this matches the first argument of node.on().
  name: 'brain-freeze',
  // Whether or not this event should bubble to the next parent.
  bubble: true,
  // The original FormKitNode that emitted the event.
  origin: node,
}

Node events (by default) bubble up the node tree, but node.on() will only respond to events emitted by the same node. However, if you would like to also catch events bubbling up from descendants you may append the string .deep to the end of your event name:

import { createNode } from '@formkit/core'

const group = createNode({ type: 'group' })

group.on('created.deep', ({ payload: child }) => {
  console.log('child node created:', child.name)
})

const child = createNode({ parent: group, name: 'party-town-usa' })
// outputs: 'child node created: party-town-usa'

Remove listener

Every call to register an observer with node.on() returns a “receipt” — a randomly generated key — that can be used later to stop observing that event (similar to setTimeout() and clearTimeout()) using node.off(receipt).

const receipt = node.on('input', ({ payload }) => {
  console.log('received input: ', payload)
})
node.input('foobar')
// outputs: 'received input: foobar'
node.off(receipt)
node.input('fizz buzz')
// no output

Core events

The following is a comprehensive list of all events emitted by @formkit/core. Third-party code may emit additional events not included here.

Emitting events

Node events are emitted with node.emit(). You can leverage this feature to emit your own synthetic events from your own plugins.

node.emit('myEvent', payloadGoesHere)

An optional third argument bubble is also available. When set to false, it prevents your event from bubbling up through the form tree.

Hooks

Hooks are middleware dispatchers that are triggered during pre-defined lifecycle operations. These hooks allow external code to extend the internal functionality of @formkit/core. The following table details all available hooks:

{
 property: string,
 classes: Record<string, boolean>
}

{
 prop: string,
 value: any
}

Hook middleware

To make use of these hooks, you must register hook middleware. A middleware is simply a function that accepts 2 arguments — the value of the hook and next — a function that calls the next middleware in the stack and returns the value.

To register a middleware, pass it to the node.hook you want to use:

import { createNode } from '@formkit/core'

const node = createNode()

// This would transform all labels to "Different label!"
node.hook.prop((payload, next) => {
  if ((payload.prop = 'label')) {
    payload.value = 'Different label!'
  }
  return next(payload)
})

Plugins

Plugins are the primary mechanism for extending the functionality of FormKit. The concept is simple — a plugin is just a function that accepts a node. These functions are then automatically called when a node is created, or when the plugin is added to the node. Plugins work similar to configuration options — they are automatically inherited by children and descendants.

import { createNode } from '@formkit/core'

// A plugin to change a prop value.
const myPlugin = (node) => {
  if (node.type === 'group') {
    node.props.color = 'yellow'
  } else {
    node.props.color = 'teal'
  }
}

const node = createNode([
  plugins: [myPlugin],
  children: [createNode()]
])

In the example above, the plugin is only defined on the parent, but the child also inherits the plugin. The function myPlugin will be called twice — once for each node in the graph (which only has two in this example):

Library

In addition to extending and modifying nodes, plugins serve one additional role — exposing input libraries. A “library” is a function assigned to the library property of a plugin that accepts a node and determines whether it knows how to “define” that node. If it does, it calls node.define() with an input definition.

For example, if we wanted to create a plugin that exposed a couple new inputs: italy and france we could write a plugin to do this:

Experienced developers will notice a few exciting properties of this plugin-library pattern:

1. Multiple input libraries can be installed on the same project.
2. Plugins (and libraries) can be exposed locally, per form, group, or globally.
3. A plugin can bundle new inputs along with plugin logic making installation simple for end users.
4. The library function has full control over what conditions result in a call to node.define(). Frequently, this is simply checking node.props.type but you can define different inputs based on other conditions, like if a particular prop is set.

Message store

Each node has its own data store. The objects in these stores are called "messages" and these messages are especially valuable for three primary use cases:

• Displaying information about the node to a user with i18n support (the validation plugin uses it).
• "Blocking" form submission.
• General data store for plugin authors.

Each message (FormKitMessage in TypeScript) in the store is an object with the following shape:

{
  // Whether or not this message blocks form submission (default: false).
  blocking: true,
  // Must be a unique string value (default: random string).
  key: 'yourkey',
  // (optional) Meta data object about this message (default: {}).
  meta: {
    // (optional) If set, i18n uses this instead of the key to find locale messages.
    messageKey: 'i18nKey',
    // (optional) If set, these arguments will be spread to the i18n locale function.
    i18nArgs: [...any],
    // (optional) If set to false, the message will check for localization.
    localize: true,
    // (optional) The message locale (default: node.config.locale)
    locale: 'en',
    // Any other meta data your heart desires.
    ...any
  },
  // An arbitrary category this message belongs to (for filtering purposes).
  // For example: 'validation' or 'success' (default: 'state')
  type: string,
  // (optional) should be a string, number, or boolean (default: undefined).
  value: 'Woops, our server is broken!',
  // Should this message be shown to end users? (default: true)
  visible: true
}

Read and write messages

To add or update a message, use node.store.set(FormKitMessage). Messages are then made available on node.store.{messageKey}

import { createMessage, createNode } from '@formkit/core'

const node = createNode()
const message = createMessage({
  key: 'clickHole',
  value: 'Please click 100 times.',
})

node.store.set(message)

console.log(node.store.clickHole.value)
// outputs: 'Please click 100 times.'

Ledger

One of the keys to FormKit’s performance is its ability to efficiently count messages matching a given criteria (in the store), and then keep a running tally of those messages as changes are made (including from child nodes). These counters are created using node.ledger.

Creating a counter

Let's say we want to count how many messages are currently being displayed. We could do this by counting messages with the visible property set to true.

Notice the second argument of node.ledger.count() is a function. This function accepts a message as an argument and expects the return value to be a boolean, indicating whether that message should be counted or not. This allows you to craft arbitrary counters for any message type.

When using a counter on a group or list node, the counter will propagate down the tree summing the value of all messages passing the criteria function and then tracking that count for store changes.