FormKit's schema is a JSON-serializable data format for storing DOM structures and component implementations including FormKit forms. Although created specifically for implementing forms, the format is capable of generating any HTML markup or using any third-party components. Schemas are rendered using FormKit's
A schema is an array of objects (called "schema nodes"), where each object defines a single HTML element, component, or text node. Simple strings produce text nodes, while components and HTML elements are defined with two different objects (referred to as
HTML elements are defined using the
$el property. You can use
$el to render any HTML element. Attributes can be added with the
attrs property, and content is assigned with the
styleattribute is unique in that it should be defined as an object of style to value pairs rather than a string.
Components can be defined with the
$cmp property. The
$cmp property should be a string that references a globally defined component or a component passed
FormKitSchema with the
libraryprop, it's best to wrap your library with Vue’s
In addition to the schema array (and optional library), the
FormKitSchema object can also include a
data prop. Values from the data object can then be referenced directly in your schema — and your schema will maintain the reactivity of the original data object.
To reference a value from the data object, you simply use a dollar sign
$ followed by the property name from the data object. References can be used in
props, conditionals and as
$— otherwise they are treated as unparsed string literals.
Schemas support calling functions that are in your original reference data — and you can even pass data references as arguments of that function!
Schemas also support logic in the form of boolean logic, comparison, and arithmetic expressions. These expressions can be used anywhere a data reference can be used (
props, conditionals, and
$. If the first element of an expression is a data reference (ex:
$count + 2), then it already begins with a
$and no further labeling is required. However, often the first character of an expression is not a dollar sign — these expressions need to be "labeled" with
$:— for example
$: ($count * 3) - 7.
Schema expressions are limited to the following operators and parenthesis:
|Strict not equals|
|Loose not equals|
|Greater than or equal|
|Less than or equal|
FormKit schema can leverage references and expressions to make schema nodes and attributes conditional. These conditionals can be added in two ways:
$cmp schema nodes can leverage an
if property that roughly equates to a
v-if in Vue. If the expression assigned to the
if property is truthy, the node is rendered, otherwise it is not.
if/then/else object allows for more complex conditional logic. It can be used to conditionally render nodes, a list of schema nodes, values of the
attrs object or values of the
props object. It is also possible to nest
if/then/else objects to create more complex structures — similar to an
if/then/elseon schema nodes
You can use the
if/then/else object anywhere you would normally use a schema node. This includes the root schema array, or the
children property of another schema node.
if/then/elseon attrs and props
You can also use
if/then/else statements to conditionally output the values of
$cmp schema nodes support looping. The loop syntax is similar to
v-for in Vue and expects an object or array to iterate over and a property to assign the current iteration value to. Optionally, you can also capture the index or property of the current iteration.
$keyto an integer before adding it to
1. To perform this cast, we simply multiplied by 1:
$key * 1before performing our addition.
Schemas can render the slot content of the
<FormKitSchema> component anywhere within the schema that a normal schema node can be rendered. All scoped slots are automatically provided to the schema under the
$slots reference object.
At times it may be necessary to pass an object of variable or unknown attributes or props to a
$el. In Vue we would do this using
v-bind — in schema land we use the
At times it may be necessary to prevent a given attribute or prop from being parsed. This can be done by prefixing an attribute or prop with
In the above example, the
__raw__ prefix will be removed, and the unparsed value of
$2.99 will be passed as the
price prop to the
Another scenario where this comes into play is rendering FormKit components. The
<FormKit> component has a
sections-schema prop that allows users to pass down schema partials to merge with various sections of their input. In this edge case, we want to pass the schema chunks to the
sectionsSchema prop with
Notice if you remove the
__raw__ prefix from the above example, the prefix no longer has effect — this is because the
Although schemas can be used for almost any purpose — the primary objective is to empower developers to build complex and dynamic forms using a serializable data format. Using the schema with FormKit inputs covers this use case well.
Assuming you globally registered the
FormKit component — you can render your
FormKit inputs from schema by using the
$cmp schema node.
The schema format has one built-in function specific to FormKit inputs: the
$get function. This builtin allows the schema to access the context object of any other FormKit input (even outside the immediate form) — provided the input in question has an explicitly declared
id prop. This allows the schema to respond conditionally to the state of your own inputs.