The official FormKit core library. This package is responsible for most of FormKit’s internal functionality. You can read documentation specifically on how it works at formkit.com.
You can add this package by using npm install @formkit/core
or yarn add @formkit/core
.
FormKit's Node object produced by createNode(). Every <FormKit />
input has 1 FormKitNode ("core node") associated with it. All inputs, forms, and groups are instances of nodes. Read more about core nodes in the architecture
documentation.
Add a child to a node. The node must be a group or list.
The added FormKitNode.
The address of the current node from the root of the tree.
Adds props to the given node by removing them from node.props.attrs and moving them to the top-level node.props object.
props
— An array of strings to be added as keys for props.The FormKitNode.
Gets a node at another address. Addresses are dot-syntax paths (or arrays) of node names. For example: form.users.0.first_name
. There are a few "special" traversal tokens as well:
$root
— Selects the root node.$parent
— Selects the parent node.$self
— Selects the current node.address
— An valid string or FormKitAddress.The found FormKitNode or undefined
.
An array of child nodes (groups and lists).
An array of FormKitNode.
Clears the errors of the node, and optionally all the children.
clearChildren
optional — If it should clear the children.sourceKey
optional — A source key to use for reset.The FormKitNode.
An object of FormKitConfig that is shared tree -wide with various configuration options that should be applied to the entire tree.
Defines the current input's library type definition including node type, schema, and props.
definition
— A FormKitTypeDefinition.Removes the node from the global registry, its parent, and emits the 'destroying' event.
Perform given callback on each of the given node's children.
callback
— A FormKitChildCallback to be called for each child.Emit an event from the node so it can be listened by on.
event
— The event name to be emitted.payload
optional — A value to be passed together with the event.bubble
optional — If the event should bubble to the parent.The FormKitNode.
Within a given tree, find a node matching a given selector. Selectors can be simple strings or a function.
selector
— A selector string.searcher
optional — A keyof FormKitNode or FormKitSearchFunction.The found FormKitNode or undefined
.
Set of hooks.
The FormKitHooks.
The index of a node compared to its siblings. This is only applicable in cases where a node is a child of a list.
A number
.
The function used to set the value of a node. All changes to a node's value should use this function as it ensures the tree's state is always fully tracked.
value
— Any value to used for the node.async
optional — If the input should happen asynchronously.A Promise<unknown>
.
Begins as false, set to true when the node is finished being created.
A boolean
.
Boolean reflecting the settlement state of the node and its subtree.
A boolean
.
A counting ledger for arbitrary message counters.
The name of the input in the node tree. When a node is a child of a list, this automatically becomes its index.
A string
.
Removes an event listener by its token. Receipts can be shared among many event listeners by explicitly declaring the "receipt" property of the listener function.
receipt
— A receipt generated by the on
function.A receipt string
.
Adds an event listener for a given event, and returns a "receipt" which is a random string token. This token should be used to remove the listener in the future. Alternatively you can assign a "receipt" property to the listener function and that receipt will be used instead. This allows multiple listeners to all be de-registered with a single off() call if they share the same receipt.
eventName
— The event name to listen to.listener
— A FormKitEventListener to run when the event happens.A receipt string
.
The parent of a node.
If found a FormKitNode or null
.
An proxied object of props. These are typically provided by the adapter of choice.
An optional list of FormKitProps.
Removes a child from the node.
node
— A FormKitNode to be removed.The FormKitNode.
Resets the node’s value back to its original value.
The FormKitNode.
Retrieves the root node of a tree. This is accomplished via tree-traversal on-request, and as such should not be used in frequently called functions.
The FormKitNode.
Sets errors on the input, and optionally to child inputs.
localErrors
— A ErrorMessages to be used.childErrors
optional — A ErrorMessages to be used for children.A promise that resolves when a node and its entire subtree is settled. In other words — all the inputs are done committing their values.
A Promise<unknown>
.
The internal node store.
A FormKitStore.
Triggers a submit event on the nearest form.
A text or translation function that exposes a given string to the "text" hook. All text shown to users should be passed through this function before being displayed — especially for core and plugin authors.
key
— A key or a FormKitTextFragment to find the translation for.The translated string
.
The type of node, should only be 'input', 'list', or 'group'.
Registers a new plugin on the node and its subtree.
plugin
— A FormKitPlugin or an Array or Set of FormKitPlugin.run
optional — Should the plugin be executed on creation.library
optional — Should the plugin's library function be executed on creation.The FormKitNode.
The value of the input. This should never be directly modified. Any desired mutations should be made through input.
Performs a function on the node and every node in its subtree. This is an expensive operation so it should be done very rarely and only lifecycle events that are relatively rare like boot up and shut down.
callback
— A FormKitChildCallback to be executed for each child.stopOnFalse
optional — If it should stop when the return is false.Perform a breadth-first search on a node subtree and locate the first instance of a match.
tree
— A FormKitNode to start from.searchValue
— A value to be searched.searchGoal
— A goal value.A FormKitNode or undefined
.
Clears errors on the node and optionally its children.
id
— The id of the node you want to clear errors for.clearChildren
— Determines if the children of this node should have their errors cleared.Compiles a logical string like "a != z || b == c"
into a single function. The return value is an object with a "provide" method that iterates over all requirement tokens to use as replacements.
expr
— A string to compile.Function that produces a standardized object representation of CSS classes.
propertyKey
— the section key.node
— A FormKitNode.sectionClassList
— A string | Record<string, boolean>
or a FormKitClasses.Record<string, boolean>
Creates a new instance of a global configuration option. This object is essentially just a FormKitOption object, but it can be used as the root for FormKitConfig's proxy and retain event "emitting".
options
— An object of optional properties of FormKitConfig.Creates a new FormKitMessage object.
conf
— An object of optional properties of FormKitMessage.node
— A FormKitNode.Creates a new instance of a FormKit Node. Nodes are the atomic unit of a FormKit graph.
options
— An options object of FormKitOptions to override the defaults.A FormKitNode.
Creates the initial value for a node based on the options passed in and the type of the input.
options
— A FormKitOptions.unknown
Deregister a node from the registry.
node
— A FormKitNode.Emits an error. Generally should result in an exception.
code
— The integer error code.data
— Usually an object of information to include.Combines multiple class lists into a single list.
node
— A FormKitNode.property
— The property key to which the class list will be applied.args
— And array of Record<string, boolean>
of CSS class list(s).string | null
Get a node by a particular id.
id
— Get a node by a given id.A FormKitNode or undefined
.
Type narrow that a node is a DOM node.
node
— A schema node to check.boolean
Determines if a node is conditionally rendered or not.
node
— A schema node to check.boolean
Type narrow that a node is a DOM node.
node
— A schema node to checkboolean
A simple type guard to determine if the context being evaluated is a list type.
arg
— A FormKitContextShape.Returns a boolean
.
Determine if a given object is a node.
node
— Any value.Returns a boolean
.
Determines if the node is syntactic sugar or not.
node
— A schema node to check.boolean
Create a name-based dictionary of all children in an array.
children
— An array of FormKitNode.A dictionary of named FormKitNode.
Registers a node to the registry if the node is a root node, or if the node has an explicit node.props.alias. If these two things are not true, then no node is registered (idempotent).
node
— A FormKitNode.Resets an input to its "initial" value. If the input is a group or list it resets all the children as well.
id
— The id of an input to reset.resetTo
— A value to reset the node to.A FormKitNode or undefined
.
Resets the global number of node registrations, useful for deterministic node naming.
Resets the entire registry. Deregisters all nodes and removes all listeners.
Sets errors on a form, group, or input.
id
— The id of a form.localErrors
— The errors to set on the form or the form’s inputs in the format of ErrorMessages.childErrors
— (optional) The errors to set on the form or the form’s inputs in the format of ErrorMessages.Submits a FormKit form programmatically.
id
— The id of the form.Converts syntactic sugar nodes to standard nodes.
node
— A node to covert.A FormKitSchemaNode without the properties of FormKitSchemaFormKit.
Globally emits a warning.
code
— The integer warning code.data
— Usually an object of information to include.A way of watching changes in the global registry.
id
— A dot-syntax id where the node is located.
callback
— A callback in the format of FormKitEventListener to notify when the node is set or removed.The callback type for node.each().
A descriptor of a child value, generally passed up a node tree.
Definition for a function that produces CSS classes.
The compiler output, a function that adds the required tokens.
General "app" like configuration options, these are automatically inherited by all children — they are not reactive.
The interface of a FormKit node's context object. A FormKit node is a proxy of this object.
Define the most basic shape of a context object for type guards trying to reason about a context's value.
The counter object used to perform instance counting within a tree.
Ledger counters require a condition function that determines if a given message applies to it or not.
The FormKitDispatcher interface is responsible creating/running "hooks".
The internal structure of a FormKitEvent.
The FormKitEventEmitter definition.
Event listener functions definition.
Defines a function that allows selectively overriding a given schema.
Context object to be created by and used by each respective UI framework. No values are created or output by FormKitCore, but this interface should be followed by each respective plugin.
The state inside a node’s framework context. Usually used to track things like blurred and validity states.
FormKit inputs of type 'group' must have keyed values by default.
Describes the data passing through the error and warning handlers.
The available hooks for middleware.
The FormKit ledger, a general-purpose message counting service provided by FormKit core for counting messages throughout a tree.
A library of inputs, keyed by the name of the type.
The simplest definition for a context of type "list".
Messages have can have any arbitrary meta data attached to them.
The structure of a core FormKitMessage. These messages are used to store information about the state of a node.
Defines the actual store of messages.
The base interface definition for a FormKitPlugin. It's just a function that accepts a node argument.
Conditions nested inside attribute declarations.
Definition for a function that can extend a given schema node.
The context that is passed from one schema render to the next.
Properties available in all schema nodes.
The definition of a FormKitTrap. These are somewhat like methods on each FormKitNode. They are always symmetrical (get/set) — although it's acceptable for either to throw an Exception.
Arbitrary data that has properties. Could be a POJO, could be an array.
Describes the path to a particular node from the top of the tree.
The possible value types of attributes (in the schema).
A function that accepts a callback with a token as the only argument, and must return a function that provides the true value of the token.
A full loop statement in tuple syntax. Can be read like "foreach value, key? in list".
The value being listed out. Can be an array, an object, or a number.
A FormKit message is immutable, so all properties should be readonly.
All FormKitMiddleware conform to the pattern of accepting a payload and a next()
function. They can either pass the payload to the next middleware explicitly (as an argument of next), or implicitly (no argument for next).
These are the types of nodes that can be created. These are different from the type of inputs available and rather describe their purpose in the tree.
Options that can be used to instantiate a new node via createNode().
The user-land per-instance "props", which are generally akin to the props passed into components on the front end.
DOM attributes are simple string dictionaries.
Properties available when defining a generic non-FormKit component.
A schema node that determines which content to render.
Properties available when using a DOM node.
Syntactic sugar for a FormKitSchemaComponent node that uses FormKit.
Properties available then defining a schema node.
A simple text node.
Breadth and depth-first searches can use a callback of this notation.
The message store contains all of the messages that pertain to a given node.
Text fragments are small pieces of text used for things like interface validation messages, or errors that may be exposed for modification or even translation.
The map signature for a node's traps Map.
Definition of a library item — when registering a new library item, these are the required and available properties.
Signature for any of the node's getter traps. Keep in mind that because these are traps and not class methods, their response types are declared explicitly in the FormKitNode interface.
The signature for a node's trap setter — these are more rare than getter traps, but can be useful for blocking access to certain context properties or modifying the behavior of an assignment (ex. see setParent).