Skip to main content

Configuration

The formik-form-builder package is fully configurable through a simple fields array and optional global settings.
Each field in your form is defined by an object that follows the FieldType structure.


FieldType Structure

Below are the available configuration options for each field:

PropertyTypeRequiredDescription
fieldstringTrueUnique field name used in form state.
typeInputTypesTrueInput type (see below available values below).
initialValueanyTrueDefault value for the field.
labelstringFalseLabel displayed above the input.
groupLabelstringFalseLabel for grouping multiple related inputs.
helperTextstringFalseAdditional hint or instruction under the field.
options[{ label: string, value: string/number, description: string },]True(for choice-based inputs else False)For choice-based inputs like checkboxes, radios, selects.
direction"row" | "column"FalseLayout direction for option-based inputs.
validationobject FalseYup validation rules for the field. Check Validation Rules
gridPropsobjectFalseMUI grid props for responsive layouts.
conditionsobjectFalseConditional display rules based on other fields.
placeholderstringFalseTo provide placeholder.
outputTypestringFalseSpecify type of output.
valueTypeCHECK_BOX_VALUE_TYPEFalseCheckbox value type (ARRAY, STRING ,BOOLEAN).
variantstring("DEFAULT" | "ICON")FalseCan be used only for RADIO InputTypes.
muiProps{any}FalseAny additional props passed to the MUI/Joy component.

Available InputTypes:

  • TEXT
  • MULTI_TEXT
  • CHECKBOX
  • SELECT
  • AUTO_COMPLETE
  • RADIO
  • DROPDOWN

Validation Rules

The validation object supports the following rules:

RuleTypeDescription
requiredbooleanWhether the field is mandatory.
messagestringError message when validation fails.
minLengthnumberMinimum allowed length.
minLengthRuleMsgstringMessage when minLength fails.
maxLengthnumberMaximum allowed length.
maxLengthRuleMsgstringMessage when maxLengthRuleMsg fails.
minValuenumberMinimum allowed value.
minValueRuleMsgstringMessage when minValueRuleMsg fails.
maxValuenumberMaximum allowed value.
maxValueRuleMsgstringMessage when maxValueRuleMsg fails.
isPositivebooleanValidate if positive value.
isPositiveRuleMsgstringMessage when it is not positive.
moreThannumberValue to compare.
moreThanRuleMsgstringMessage when it is not more than.
lessThannumberValue to compare.
lessThanRuleMsgstringMessage when it is not less than.
patternRegExpRegex pattern for validation.
patternRuleMsgstringMessage when pattern fails.
yupCustomValidationYup.TestConfig<string | number | boolean | string[] | number[] | boolean[] | undefined | null>Adds a custom Yup test. Useful for advanced or conditional validation logic.

Conditional Rendering

The conditions property allows you to define conditional logic for showing, hiding, enabling, or disabling fields based on the values of other fields.

PropertyTypeDescription
actionConditionActionSpecifies what to do when the conditions are met (e.g., SHOW, HIDE, DISABLE, ENABLE).
groups[{group, groupPostCondition,logic: [{}] }]An array of condition groups. Each group contains one or more conditions (logic) that must be evaluated together.
groupstringThe group name for organizing related conditions.
groupPostConditionPostCondition.AND | ORDefines how this group’s result combines with other groups.
logic[{field, value, condition, postCondition}]An array of individual conditions to check within a group.
fieldstringThe field key whose value will be checked.
valuestring | number | boolean | null | undefined | Array<...>The value to compare against.
conditionConditionNameThe type of comparison to perform (see available values below).
postConditionPostCondition.AND | ORDefines how this condition combines with others in the same group.

Available Enum Values

ConditionAction

  • SHOW — Make the field visible.
  • HIDE — Hide the field.
  • DISABLE — Disable the field (read-only).
  • ENABLE — Enable the field.

ConditionName

  • EQUALS
  • NOT_EQUALS
  • GREATER_THAN
  • LESS_THAN
  • GREATER_THAN_OR_EQUAL
  • LESS_THAN_OR_EQUAL
  • CONTAINS
  • NOT_CONTAINS
  • STARTS_WITH
  • ENDS_WITH
  • IS_EMPTY
  • IS_NOT_EMPTY
  • INCLUDES
  • NOT_INCLUDES
  • ARRAY_EQUALS

PostCondition

  • AND — All conditions/groups must be true.
  • OR — At least one condition/group must be true.

Example:

conditions: {
action: ConditionAction.SHOW,
groups: [
{
group: "check",
groupPostCondition: PostCondition.AND,
logic: [
{
field: "test.firstName",
value: "10",
condition: ConditionName.EQUALS,
postCondition: PostCondition.AND
}
]
}
]
}

Using useFormBuilder Hook

The useFormBuilder hook generates initial form values and a Yup validation schema from your fields configuration.

import { useFormBuilder } from "formik-form-builder";
const { initialValues, yupSchemaValidation } = useFormBuilder(fields);
NameTypeDescription
initialValueobjectAn object containing the default values for each field, based on the initialValue property in your field definitions.
yupSchemaValidationYup.ObjectSchemaA Yup validation schema automatically built from the validation rules defined in the fields array.

It is not needed when using <FormikRenderer/>


Global Settings

<FormikRenderer/>

The Formik component is used to manage form state, validation, and submission. You should pass this props to <Formik/> :

PropDescription
fieldsArray of field configurations.
onSubmitA callback function that is called for form submission.
onReset(optional)A callback function to reset from inputs.

Check </FormikRenderer> usage example.

Formik Integration

<Formik/>

The Formik component is used to manage form state, validation, and submission when you want more control. You can use this for all but there is a shorter alternative when you don't need to control which is: <FormikRenderer/>. You should pass this props to <Formik/> :

PropDescription
initialValuesThe initial values for the form fields. To be passed from the destructured data of useFormBuilder hook.
validationSchemaThe Yup validation schema. To be passed from the destructured data of useFormBuilder hook.
onSubmitA callback function that is called for form submission.
onReset(optional)A callback function to reset from inputs.

<FormBuilder />

A custom component that renders the form fields based on the fields array which should be wrap inside a <Form>. You should pass this global configuration props to <FormBuilder /> :

PropDescription
groupGroup name for fields.
valuesCurrent form values from Formik.
data-testTest identifier for automated testing.
fieldsArray of field configurations.

Check usage Example.

Form Submission

When the form is submitted, the onSubmit function is called, which is used to handle the form submission. Example of it:

onSubmit={(values, actions) => {
console.log(values);
alert(JSON.stringify(values, null, 2));
actions.setSubmitting(false);
}}