@formkit/inputs

Introduction

The official FormKit Inputs plugin. This package contains the source code for all native HTML input types. Read the inputs documentation for usage instructions.

Helpers

$attrs()

Applies attributes to a given schema section by applying a higher order function that merges a given set of attributes into the node.

Signature

$attrs(attrs: FormKitSchemaAttributes | (() => FormKitSchemaAttributes), section: FormKitSchemaExtendableSection): FormKitSchemaExtendableSection;

Parameters

Returns

FormKitSchemaExtendableSection

$extend()

Extends a schema node with a given set of extensions.

Signature

$extend(section: FormKitSchemaExtendableSection, extendWith: Partial<FormKitSchemaNode>): FormKitSchemaExtendableSection;

Parameters

  • section — A section to apply an extension to.
  • extendWith — A partial schema snippet to apply to the section.

Returns

FormKitSchemaExtendableSection

$for()

Applies a condition to a given schema section.

Signature

$for(varName: string, inName: string, section: FormKitSchemaExtendableSection): (extensions: Record<string, Partial<FormKitSchemaNode>>) => FormKitSchemaNode;

Parameters

  • varName — The name of the variable that holds the current instance.
  • inName — The variable we are iterating over.
  • section — A section to repeat.

Returns

FormKitSchemaExtendableSection

$if()

Applies a condition to a given schema section.

Signature

$if(condition: string, then: FormKitSchemaExtendableSection, otherwise?: FormKitSchemaExtendableSection): FormKitSchemaExtendableSection;

Parameters

  • condition — A schema condition to apply to a section.
  • then — The section that applies if the condition is true.
  • otherwise optional — (else) The section that applies if the condition is false.

Returns

FormKitSchemaExtendableSection

$root()

Creates a root schema section.

Signature

$root(section: FormKitSchemaExtendableSection): FormKitExtendableSchemaRoot;

Parameters

  • section — A section to make a root from.

Returns

FormKitSchemaExtendableSection

Features

checkboxes()

A feature that adds checkbox selection support.

Signature

checkboxes(node: FormKitNode): void;

Parameters

defaultIcon()

Adds icon props definition.

Signature

defaultIcon(sectionKey: string, defaultIcon: string): (node: FormKitNode) => void;

Parameters

  • sectionKey — the location the icon should be loaded.
  • defaultIcon — the icon that should be loaded if a match is found in the user's CSS.

Returns

A FormKitPlugin.

files()

A feature to add file handling support to an input.

Signature

files(node: FormKitNode): void;

Parameters

initialValue()

A feature that ensures the input has an initialValue prop.

Signature

initialValue(node: FormKitNode): void;

Parameters

localize()

Creates a new feature that generates a localization message of type ui for use on a given component.

Signature

localize(key: string, value?: string): (node: FormKitNode) => void;

Parameters

  • key — The key of the message.
  • value * optional * — The value of the message.

Returns

A FormKitPlugin.

normalizeBoxes()

A feature that normalizes box types (checkboxes, radios).

Signature

normalizeBoxes(node: FormKitNode): FormKitMiddleware<{
    prop: string | symbol;
    value: any;
}>;

Parameters

Returns

A FormKitMiddleware.

options()

A feature that converts the options prop to usable values, to be used by a feature or a plugin.

Signature

options(node: FormKitNode): void;

Parameters

radios()

A feature to check if the value being checked is the current value.

Signature

radios(node: FormKitNode): void;

Parameters

Functions

createLibraryPlugin()

Creates a plugin based on a list of FormKitLibrary.

Signature

createLibraryPlugin(...libraries: FormKitLibrary[]): FormKitPlugin;

Parameters

Returns

FormKitPlugin

createSection()

Creates a new reusable section.

Signature

createSection(section: string, el: string | null | (() => FormKitSchemaNode), fragment: true): FormKitSection<FormKitExtendableSchemaRoot>;
createSection(section: string, el: string | null | (() => FormKitSchemaNode)): FormKitSection<FormKitSchemaExtendableSection>;
createSection(section: string, el: string | (() => FormKitSchemaNode), fragment: false): FormKitSection<FormKitSchemaExtendableSection>;

Parameters

  • section — A single section of schema
  • el — The element or a function that returns a schema node.
  • fragment

Returns

Returns a FormKitExtendableSchemaRoot or a FormKitSchemaExtendableSection.

disables()

A feature that allows disabling children of this node.

Signature

disables(node: FormKitNode): void;

Parameters

eachSection()

Runs a callback over every section in a schema. if stopOnCallbackReturn is true and the callback returns a value, the loop will stop and return that value.

Signature

eachSection<T>(schema: FormKitSchemaDefinition, callback: (section: FormKitSchemaComponent | FormKitSchemaDOMNode, schemaParent: FormKitSchemaNode[], schema: FormKitSchemaCondition) => T, stopOnCallbackReturn?: boolean, schemaParent?: FormKitSchemaNode[]): T | void;

Parameters

  • schema — A FormKitSchemaNode array.
  • callback — A callback to run on every section.
  • stopOnCallbackReturn * optional * — If true, the loop will stop if the callback returns a value.
  • schemaParent * optional * — The parent of the current schema node.

Returns

extendSchema()

Extends a single schema node with an extension. The extension can be any partial node including strings.

Signature

extendSchema(schema: FormKitSchemaNode, extension?: Partial<FormKitSchemaNode>): FormKitSchemaNode;

Parameters

  • schema — The base schema node.
  • extension * optional * — The values to extend on the base schema node.

Returns

FormKitSchemaNode

findSection()

Finds a seciton by name in a schema.

Signature

findSection(schema: FormKitSchemaDefinition, target: string): [false, false] | [FormKitSchemaNode[] | false, FormKitSchemaCondition];

Parameters

Returns

a tuple of the schema and the section or a tuple of false and false if not found.

form()

A feature to add a submit handler and actions section.

Signature

form(node: FormKitNode): void;

Parameters

ignore()

A feature that applies ignore="true" by default.

Signature

ignore(node: FormKitNode): void;

Parameters

isSchemaObject()

Type guard for schema objects.

Signature

isSchemaObject(schema: Partial<FormKitSchemaNode>): schema is FormKitSchemaDOMNode | FormKitSchemaComponent | FormKitSchemaFormKit;

Parameters

  • schema — returns true if the node is a schema node but not a string or conditional.

Returns

boolean

isSlotCondition()

Checks if the current schema node is a slot condition.

Signature

isSlotCondition(node: FormKitSchemaNode): node is {
    if: string;
    then: string;
    else: FormKitSchemaNode | FormKitSchemaNode[];
};

Parameters

Returns

boolean

Examples

{
 if: '$slot.name',
 then: '$slot.name',
 else: []
} // this schema node would return true.

normalizeOptions()

A function to normalize an array of objects, array of strings, or object of key-values to use an array of objects with value and label properties.

Signature

normalizeOptions(options: FormKitOptionsProp): FormKitOptionsList;

Parameters

Returns

A list of FormKitOptionsList.

select()

Converts the options prop to usable values.

Signature

select(node: FormKitNode): void;

Parameters

  • node — A formkit node.

useSchema()

Creates an input schema with all of the wrapping base schema.

Signature

useSchema(inputSection: FormKitSection): FormKitSchemaExtendableSection;

Parameters

  • inputSection — Content to store in the input section key location.

Returns

FormKitExtendableSchemaRoot

TypeScript

FormKitFile

A single file object in FormKit’s synthetic "FileList".

interface FormKitFile {
    file?: File;
    name: string;
}

FormKitOptionsItem

Options should always be formatted as an array of objects with label and value properties.

interface FormKitOptionsItem {
    __original?: any;
    [index: string]: any;
    attrs?:{
        disabled?: boolean;
    }&Record<string, any>;
    label: string;
    value: unknown;
}

FormKitOptionsPropExtensions

Allows for prop extensions to be defined by using an interface whose keys are ignored, but values are applied to a union type. This allows for any third party code to extend the options prop by using module augmentation to add new values to the union type.

interface FormKitOptionsPropExtensions {
    arrayOfNumbers: number[];
    arrayOfStrings: string[];
    optionsList: FormKitOptionsList;
    valueLabelPojo: Record<string | number, string>;
}

FormKitSchemaExtendableSection

A function that is called with an extensions argument and returns a valid schema node.

interface FormKitSchemaExtendableSection {
    _s?: string;
    (extensions: Record<string, Partial<FormKitSchemaNode>>): FormKitSchemaNode;
}

FormKitSection

A function that when called, returns a function that can in turn be called with an extension parameter.

interface FormKitSection<T = FormKitSchemaExtendableSection> {
    (...children: Array<FormKitSchemaExtendableSection | string>): T;
}

FormKitSyntheticPropsExtensions

Synthetic props are props that are not explicitly declared as props, but should be treated as props to the outside world.

interface FormKitSyntheticPropsExtensions {
    accept: string;
    action: string;
    actions: boolean;
    dirtyBehavior:'touched' | 'compare';
    disabled: string | boolean;
    enctype: string;
    help: string;
    ignore: string | boolean;
    label: string;
    max: string | number;
    method: string;
    min: string | number;
    multiple: string | boolean;
    options: FormKitOptionsProp;
    preserve: string | boolean;
    preserveErrors: string | boolean;
    step: string | number;
}

FormKitFileValue

A synthetic array-based "FileList".

type FormKitFileValue = FormKitFile[];

FormKitInputSchema

Either a schema node, or a function that returns a schema node.

type FormKitInputSchema = ((children?: FormKitSchemaDefinition) => FormKitSchemaNode) | FormKitSchemaNode;

FormKitOptionsList

An array of option items.

type FormKitOptionsList = FormKitOptionsItem[];

FormKitOptionsProp

The types of options that can be passed to the options prop.

type FormKitOptionsProp = FormKitOptionsPropExtensions[keyof FormKitOptionsPropExtensions];

FormKitSyntheticProps

The synthetic prop types.

type FormKitSyntheticProps = {
    [Property in keyof FormKitSyntheticPropsExtensions]: FormKitSyntheticPropsExtensions[Property];
};